PSRule for Azure

A suite of rules to test Azure resources and infrastructure as code (IaC) using PSRule.

Features of PSRule for Azure include:

• Learn by example - Fix issues quickly, and learn how to improve your Infrastructure as Code..
• Framework aligned - Apply principals of Azure Well-Architected Framework to your workloads.
• Start day one - Leverage over 400 pre-built rules to test Azure resources.
• DevOps integrated - Test Azure infrastructure as code such as Bicep or Azure Resource Manager templates.
• Cross-platform - Run locally or in the cloud on MacOS, Linux, and Windows.
• Open community - Open source rules for the Azure community.

Project objectives

1. Ready to go:
   • Provide a Azure Well-Architected Framework aligned suite of rules for validating Azure resources.
   • Provide meaningful information to allow remediation.
2. DevOps:
   • Resources and Azure code can be tested before deployment within DevOps workflows.
   • Allow pull request (PR) validation to prevent invalid configuration from being merged.
3. Enterprise ready:
   • Rules can be directly adopted and additional enterprise specific rules can be layed on.
   • Provide regular baselines to allow progressive adoption.

Support

This project uses GitHub Issues to track bugs and feature requests. Before logging an issue please see our troubleshooting guide.

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 modules

This project requires the PSRule and Az PowerShell modules. For details on each see install.

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

For rule and integration modules see related projects.

Getting started

PSRule for Azure provides two methods for analyzing Azure resources:

• Pre-flight - Before resources are deployed from Azure Resource Manager templates.
• In-flight - After resources are deployed to an Azure subscription.

For specific use cases see scenarios. For additional details see the FAQ.

To get started with a sample repository, see PSRule for Azure Quick Start on GitHub.

Using with GitHub Actions

The following example shows how to setup GitHub Actions to validate templates pre-flight.

1. See Creating a workflow file.
2. Reference microsoft/ps-rule with modules: 'PSRule.Rules.Azure'.

For example:

# Example: .github/workflows/analyze-arm.yaml

#
# STEP 1: Template validation
#
name: Analyze templates
on:
  push:
    branches:
    - main
  pull_request:
    branches:
    - main
jobs:
  analyze_arm:
    name: Analyze templates
    runs-on: ubuntu-latest
    steps:

    - name: Checkout
      uses: actions/checkout@v3

    # STEP 2: Run analysis against exported data
    - name: Analyze Azure template files
      uses: microsoft/ps-rule@v2.9.0
      with:
        modules: 'PSRule.Rules.Azure'  # Analyze objects using the rules within the PSRule.Rules.Azure PowerShell module.

Using with Azure Pipelines

The following example shows how to setup Azure Pipelines to validate templates pre-flight.

1. Install PSRule extension for Azure DevOps marketplace.
2. Create a new YAML pipeline with the Starter pipeline template.
3. Add the Install PSRule module task.
   • Set module to PSRule.Rules.Azure.
4. Add the PSRule analysis task.
   • Set input type to repository.
   • Set modules to PSRule.Rules.Azure.

For example:

# Example: .azure-pipelines/analyze-arm.yaml

#
# STEP 2: Template validation
#
jobs:
- job: 'analyze_arm'
  displayName: 'Analyze templates'
  pool:
    vmImage: 'ubuntu-22.04'
  steps:

  # STEP 3: Install PSRule.Rules.Azure from the PowerShell Gallery
  - task: ps-rule-install@2
    displayName: Install PSRule.Rules.Azure
    inputs:
      module: 'PSRule.Rules.Azure'   # Install PSRule.Rules.Azure from the PowerShell Gallery.

  # STEP 4: Run analysis against exported data
  - task: ps-rule-assert@2
    displayName: Analyze Azure template files
    inputs:
      modules: 'PSRule.Rules.Azure'   # Analyze objects using the rules within the PSRule.Rules.Azure PowerShell module.

Using locally

The following example shows how to setup PSRule locally to validate templates pre-flight.

1. Install the PSRule.Rules.Azure module and dependencies from the PowerShell Gallery.
2. Run analysis against repository files.

For example:

# STEP 1: Install PSRule.Rules.Azure from the PowerShell Gallery
Install-Module -Name 'PSRule.Rules.Azure' -Scope CurrentUser;

# STEP 2: Run analysis against exported data
Assert-PSRule -Module 'PSRule.Rules.Azure' -InputPath 'out/templates/' -Format File;

Export in-flight resource data

The following example shows how to setup PSRule locally to validate resources running in a subscription.

1. Install the PSRule.Rules.Azure module and dependencies from the PowerShell Gallery.
2. Connect and set context to an Azure subscription from PowerShell.
3. Export the resource data with the Export-AzRuleData cmdlet.
4. Run analysis against exported data.

For example:

# STEP 1: Install PSRule.Rules.Azure from the PowerShell Gallery
Install-Module -Name 'PSRule.Rules.Azure' -Scope CurrentUser;

# STEP 2: Authenticate to Azure, only required if not currently connected
Connect-AzAccount;

# Confirm the current subscription context
Get-AzContext;

# STEP 3: Exports a resource graph stored as JSON for analysis
Export-AzRuleData -OutputPath 'out/templates/';

# STEP 4: Run analysis against exported data
Assert-PSRule -Module 'PSRule.Rules.Azure' -InputPath 'out/templates/';

Additional options

By default, resource data for the current subscription context will be exported.

To export resource data for specific subscriptions use:

• -Subscription - to specify subscriptions by id or name.
• -Tenant - to specify subscriptions within an Azure Active Directory Tenant by id.

For example:

# Export data from two specific subscriptions
Export-AzRuleData -Subscription 'Contoso Production', 'Contoso Non-production';

To export specific resource data use:

• -ResourceGroupName - to filter resources by Resource Group.
• -Tag - to filter resources based on tag.

For example:

# Export information from two resource groups within the current subscription context
Export-AzRuleData -ResourceGroupName 'rg-app1-web', 'rg-app1-db';

To export resource data for all subscription contexts use:

• -All - to export resource data for all subscription contexts.

For example:

# Export data from all subscription contexts
Export-AzRuleData -All;

To filter results to only failed rules, use Invoke-PSRule -Outcome Fail. Passed, failed and error results are shown by default.

For example:

# Only show failed results
Invoke-PSRule -InputPath 'out/templates/' -Module 'PSRule.Rules.Azure' -Outcome Fail;

The output of this example is:

   TargetName: storage

RuleName                            Outcome    Recommendation
--------                            -------    --------------
Azure.Storage.UseReplication        Fail       Storage accounts not using GRS may be at risk
Azure.Storage.SecureTransferRequ... Fail       Storage accounts should only accept secure traffic
Azure.Storage.SoftDelete            Fail       Enable soft delete on Storage Accounts

A summary of results can be displayed by using Invoke-PSRule -As Summary.

For example:

# Display as summary results
Invoke-PSRule -InputPath 'out/templates/' -Module 'PSRule.Rules.Azure' -As Summary;

The output of this example is:

RuleName                            Pass  Fail  Outcome
--------                            ----  ----  -------
Azure.ACR.MinSku                    0     1     Fail
Azure.AppService.PlanInstanceCount  0     1     Fail
Azure.AppService.UseHTTPS           0     2     Fail
Azure.Resource.UseTags              73    36    Fail
Azure.SQL.ThreatDetection           0     1     Fail
Azure.SQL.Auditing                  0     1     Fail
Azure.Storage.UseReplication        1     7     Fail
Azure.Storage.SecureTransferRequ... 2     6     Fail
Azure.Storage.SoftDelete            0     8     Fail

Scenarios

For walk through examples of PSRule for Azure module usage see:

• Validate Azure resources from templates with Azure Pipelines
• Validate Azure resources from templates with continuous integration (CI)
• Create a custom rule to enforce Resource Group tagging
• Create a custom rule to enforce code ownership

Rule reference

PSRule for Azure includes rules across five pillars of the Microsoft Azure Well-Architected Framework.

• Rules for architecture excellence
  • Cost Optimization
  • Operational Excellence
  • Performance Efficiency
  • Reliability
  • Security

To view a list of rules by Azure resources see:

• Rules by resource

Baseline reference

For a list of baselines you can use in your configuration see Baselines.

Language reference

PSRule for Azure extends PowerShell with the following cmdlets.

Commands

PSRule for Azure included the following cmdlets:

• Export-AzRuleData - Export resource configuration data from Azure subscriptions.
• Export-AzRuleTemplateData - Export resource configuration data from Azure templates.
• Export-AzPolicyAssignmentData - Export policy assignment data.
• Export-AzPolicyAssignmentRuleData - Export JSON based rules from policy assignment data.
• Get-AzRuleTemplateLink - Get a metadata link to a Azure template file.
• Get-AzPolicyAssignmentDataSource - Get policy assignment sources.

Concepts

To find out more, look at these conceptual topics:

• Getting started:
  • How to install PSRule for Azure
  • Creating your pipeline
• Testing infrastructure as code:
  • Expanding source files
  • Using templates
  • Using Bicep source
  • Working with baselines
• Setup:
  • Configuring options
  • Configuring rule defaults
  • Configuring expansion
  • Setup Bicep
  • Setup Azure Monitor logs

Related projects

For a list of projects and integrations see Related projects.

Changes and versioning

This repository uses semantic versioning to declare breaking changes. For details please see the changes and versioning.

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 opencode@microsoft.com with any additional questions or comments.

Maintainers

• Bernie White

License

This project is licensed under the MIT License.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.