Azure Quick Review

• 1: Overview
• 2: Plugins
• 2.1: Internal Plugins
• 3: Install
• 4: Usage
• 5: Recommendations
• 6: Troubleshooting & Support
• 7: Contribution Guidelines
• 8: Resources & References
• 9: Related Projects
• 10: Profiling azqr

1 - Overview

Azure Quick Review (azqr) is a powerful command-line interface (CLI) tool that specializes in analyzing Azure resources to ensure compliance with Azure’s best practices and recommendations. Its main objective is to offer users a comprehensive overview of their Azure resources, allowing them to easily identify any non-compliant configurations or areas for improvement.

Azure Quick Review Recommendations

Azure Quick Review (azqr) scans your resources with 2 types of recommendations:

• Azure Resource Graph (ARG) queries provided by the Azure Proactive Resiliency Library v2 (APRL) and the Azure Orphaned Resources (https://github.com/dolevshor/azure-orphan-resources) projects
• Azure Resource Manager (ARM) rules built with the Azure Golang SDK

To learn more about the recommendations used by Azure Quick Review (azqr), you can refer to the documentation available here.

Scan Results

The output generated by Azure Quick Review (azqr) is written by default to an Excel file, which contains the following sheets:

Core Sheets (always generated)

• Recommendations: Action plan listing all recommendations with the count of impacted resources.
• ImpactedResources: Resources that have issues to address.
• ResourceTypes: Summary of impacted resource types.
• Inventory: All scanned resources with details (SKU, Tier, Kind, calculated SLA).
• OutOfScope: Resources that were not scanned.

Optional Sheets (enabled by default)

• Advisor: Recommendations from Azure Advisor. Disable with --stages -advisor.
• Defender: Microsoft Defender for Cloud plans and tiers. Disable with --stages -defender.

Optional Sheets (disabled by default)

• DefenderRecommendations: Defender for Cloud recommendations. Enable with --stages defender-recommendations.
• Azure Policy: Non-compliant resources based on Azure Policy. Enable with --stages policy.
• Arc SQL: Azure Arc-enabled SQL Server instances. Enable with --stages arc.
• Costs: Cost data for the last calendar month. Enable with --stages cost.

By default, Azure Quick Review (azqr) obfuscates the Subscription Ids in the output to ensure the protection of sensitive information and maintain data privacy and security. If you want to display the Subscription Ids without obfuscation, you can use the --mask=false flag when executing the tool.

Azure Quick Review can also generate an csv files with the same information as the excel. To generate the csv files, you can use the --csv flag when running the tool.

Supported Azure Services

Azure Quick Review (azqr) currently supports the following Azure services:

Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct

Trademark Notice

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.

2 - Plugins

Overview

YAML plugins provide a simple, declarative way to extend azqr with custom Azure Resource Graph (ARG) queries without writing Go code. This is ideal for:

• Quick custom checks and validations
• Organization-specific compliance rules
• Temporary or experimental recommendations
• Non-developers who want to extend azqr

Plugin Structure

A YAML plugin consists of a single .yaml file containing plugin metadata and one or more Azure Resource Graph queries.

Basic Structure

name: plugin-name
version: 1.0.0
description: Brief description of what this plugin does
author: Plugin Author Name (optional)
license: MIT (optional)

queries:
  - aprlGuid: unique-id-001
    description: Short description of the recommendation
    longDescription: |
      Detailed description of the issue and why it matters.
      Can be multiple lines.
    recommendationControl: Category Name
    recommendationImpact: Impact Level
    recommendationResourceType: Microsoft.Service/resourceType
    learnMoreLink:
      - name: Documentation Title
        url: https://learn.microsoft.com/...
    query: |
      resources
      | where type =~ 'microsoft.service/resourcetype'
      | where some_condition == true
      | project id, name, resourceGroup, location

Required Fields

Plugin Level

• name: Unique plugin identifier (string)
• version: Semantic version (e.g., “1.0.0”)
• description: What the plugin does

Query Level

• aprlGuid: Unique identifier for the recommendation
• description: Short recommendation title
• recommendationControl: Category (see Categories section)
• recommendationImpact: Impact level (High, Medium, Low)
• recommendationResourceType: Azure resource type (e.g., “Microsoft.Storage/storageAccounts”)
• query OR queryFile: The KQL query to execute

Optional Fields

Plugin Level

• author: Plugin author name
• license: License type (e.g., MIT, Apache-2.0)

Query Level

• longDescription: Detailed explanation
• learnMoreLink: Array of documentation links
• recommendationTypeId: Azure Policy or APRL recommendation ID
• recommendationMetadataState: State (Active, Deprecated)
• potentialBenefits: Benefits of implementing the recommendation
• pgVerified: Whether verified by product group (boolean)
• automationAvailable: Whether automation is available (boolean)
• tags: Array of tags for categorization

Categories

Valid values for recommendationControl:

• High Availability: Availability and redundancy
• Security: Security and access control
• Disaster Recovery: Backup and recovery
• Scalability: Scaling and performance
• Governance: Compliance and governance
• Monitoring and Alerting: Observability
• Business Continuity: Business continuity planning
• Service Upgrade and Retirement: Service lifecycle
• Other Best Practices: General best practices (default)

Impact Levels

Valid values for recommendationImpact:

• High: Critical issues that should be addressed immediately
• Medium: Important issues that should be addressed soon (default)
• Low: Nice-to-have improvements

Query Format

Inline Query

Include the KQL query directly in the YAML file:

queries:
  - aprlGuid: example-001
    description: Example recommendation
    recommendationControl: Security
    recommendationImpact: High
    recommendationResourceType: Microsoft.Storage/storageAccounts
    query: |
      resources
      | where type =~ 'microsoft.storage/storageaccounts'
      | where properties.supportsHttpsTrafficOnly == false
      | project id, name, resourceGroup, location

External Query File

Reference an external .kql file:

queries:
  - aprlGuid: example-002
    description: Example with external query
    recommendationControl: Governance
    recommendationImpact: Medium
    recommendationResourceType: Microsoft.Network/publicIPAddresses
    queryFile: ./kql/unused-public-ips.kql

The path is relative to the YAML file location. Create a kql/ subdirectory next to your plugin YAML file.

Query Requirements

Your Azure Resource Graph queries must:

1. Return resources: Query the resources table

2. Project required fields: Include at minimum:

   • id: Resource ID
   • name: Resource name
   • resourceGroup: Resource group name
   • location: Azure region

3. Filter appropriately: Use where clauses to identify non-compliant resources

4. Use case-insensitive comparisons: Use =~ instead of == for type comparisons

Query Example

resources
| where type =~ 'microsoft.network/networkinterfaces'
| where properties.virtualMachine == "" or isnull(properties.virtualMachine)
| where properties.privateEndpoint == "" or isnull(properties.privateEndpoint)
| project id, name, resourceGroup, location,
          tags,
          sku = properties.ipConfigurations[0].properties.privateIPAllocationMethod

Plugin Discovery

YAML plugins are discovered from the following locations:

1. Current directory: ./plugins/*.yaml
2. User plugins directory: ~/.azqr/plugins/*.yaml
3. System plugins directory: /etc/azqr/plugins/*.yaml (Linux/macOS)

azqr searches recursively in these directories for any .yaml or .yml files.

Complete Example

Here’s a complete example plugin (custom-checks.yaml):

name: example-custom-checks
version: 1.0.0
description: Example YAML plugin with custom Azure Resource Graph queries
author: Azure Quick Review Team
license: MIT

queries:
  # Check for unused network interfaces
  - description: Network interfaces not attached to any VM
    aprlGuid: yaml-001-unused-nics
    recommendationTypeId: null
    recommendationControl: Governance
    recommendationImpact: Low
    recommendationResourceType: Microsoft.Network/networkInterfaces
    recommendationMetadataState: Active
    longDescription: |
      Network interfaces that are not attached to any virtual machine.
      These resources incur costs and should be reviewed for cleanup.
    potentialBenefits: Cost optimization and resource cleanup
    pgVerified: false
    automationAvailable: false
    tags:
      - cost-optimization
      - cleanup
    learnMoreLink:
      - name: Network Interface Overview
        url: "https://learn.microsoft.com/azure/virtual-network/virtual-network-network-interface"
    query: |
      resources
      | where type =~ 'Microsoft.Network/networkInterfaces'
      | where properties.virtualMachine == "" or isnull(properties.virtualMachine)
      | where properties.privateEndpoint == "" or isnull(properties.privateEndpoint)
      | project id, name, resourceGroup, location, tags

  # Check for unused public IPs (from external file)
  - description: Public IP addresses not associated with any resource
    aprlGuid: yaml-002-unused-public-ips
    recommendationControl: Governance
    recommendationImpact: Medium
    recommendationResourceType: Microsoft.Network/publicIPAddresses
    longDescription: |
      Public IP addresses that are not associated with any Azure resource.
      These IPs cost money even when not in use.
    learnMoreLink:
      - name: Public IP Addresses
        url: "https://learn.microsoft.com/azure/virtual-network/ip-services/public-ip-addresses"
    queryFile: kql/unused-public-ips.kql

  # Security check
  - description: Storage accounts without secure transfer enabled
    aprlGuid: yaml-003-storage-secure-transfer
    recommendationControl: Security
    recommendationImpact: High
    recommendationResourceType: Microsoft.Storage/storageAccounts
    longDescription: |
      Storage accounts that do not have secure transfer (HTTPS) required.
      This is a security risk as data can be transmitted over insecure connections.
    potentialBenefits: Improved security and data protection
    learnMoreLink:
      - name: Require secure transfer
        url: "https://learn.microsoft.com/azure/storage/common/storage-require-secure-transfer"
    query: |
      resources
      | where type =~ 'Microsoft.Storage/storageAccounts'
      | where properties.supportsHttpsTrafficOnly == false
      | project id, name, resourceGroup, location,
                sku = sku.name,
                tier = sku.tier

Usage

Once you’ve created your YAML plugin:

1. Place the file in one of the plugin directories

2. Run azqr scan as normal:

   azqr scan
   

3. View plugin info:

   azqr plugins list
   azqr plugins info <plugin-name>
   

The recommendations from your YAML plugin will be included in all outputs (Excel, CSV, JSON) alongside built-in recommendations.

Best Practices

1. Use Descriptive Names

name: org-security-checks
description: Organization-specific security compliance checks

2. Group Related Checks

Put related recommendations in the same plugin file:

name: network-optimization
queries:
  - aprlGuid: net-001-unused-nics
    description: Unused network interfaces
    ...
  - aprlGuid: net-002-unused-ips
    description: Unused public IPs
    ...

3. Version Your Plugins

Follow semantic versioning:

• 1.0.0: Initial release
• 1.1.0: Add new queries
• 2.0.0: Breaking changes

4. Provide Learn More Links

Always include documentation links:

learnMoreLink:
  - name: Official Documentation
    url: https://learn.microsoft.com/...
  - name: Best Practices Guide
    url: https://learn.microsoft.com/...

5. Test Your Queries

Test queries in Azure Resource Graph Explorer first:

• https://portal.azure.com/#view/HubsExtension/ArgQueryBlade

6. Use External Files for Complex Queries

For queries over ~10 lines, use external .kql files:

my-plugin/
├── custom-checks.yaml
└── kql/
    ├── query1.kql
    ├── query2.kql
    └── query3.kql

7. Document Your Plugin

Include comprehensive descriptions:

longDescription: |
  This check identifies resources that...
  
  Why it matters:
  - Cost implications
  - Security risks
  - Performance impact
  
  How to fix:
  1. Step one
  2. Step two

Troubleshooting

Plugin Not Discovered

1. Check the file extension (.yaml or .yml)
2. Verify the file is in a plugin directory
3. Run with debug logging:

   azqr scan --debug
   

Query Errors

1. Syntax errors: Test the query in Azure Resource Graph Explorer
2. No results: Verify the resource type filter
3. Permission errors: Ensure you have Reader access to subscriptions

Invalid YAML

Use a YAML validator to check syntax:

yamllint custom-checks.yaml

Limitations

1. Query-based only: YAML plugins can only use Azure Resource Graph queries, not ARM API calls
2. Subscription scope: Queries run within subscription context
3. No custom logic: Cannot include complex evaluation logic (use built-in plugins for that)

Migration from Graph Queries

If you have existing ARG queries, convert them to YAML plugins:

Before (separate .kql files):

resources
| where type =~ 'microsoft.storage/storageaccounts'
| where properties.supportsHttpsTrafficOnly == false

After (YAML plugin):

name: my-checks
version: 1.0.0
description: My custom checks
queries:
  - aprlGuid: check-001
    description: Storage accounts without HTTPS
    recommendationControl: Security
    recommendationImpact: High
    recommendationResourceType: Microsoft.Storage/storageAccounts
    query: |
      resources
      | where type =~ 'microsoft.storage/storageaccounts'
      | where properties.supportsHttpsTrafficOnly == false
      | project id, name, resourceGroup, location

2.1 - Internal Plugins

Overview

Azure Quick Review (azqr) includes internal plugins - specialized built-in scanners that provide advanced analytics beyond standard best practice recommendations. Unlike YAML plugins (which add custom Resource Graph queries), internal plugins perform complex data analysis, API integrations, and multi-source data correlation.

Internal plugins are disabled by default and must be explicitly enabled using command-line flags.

Available Internal Plugins

1. OpenAI Throttling

Plugin Name: openai-throttling
Command: azqr openai-throttling
Flag: --plugin openai-throttling
Version: 1.0.0

Monitors Azure OpenAI and Cognitive Services accounts for throttling (429 errors) to identify capacity constraints.

Key Features:

• Tracks 429 throttling errors by hour, model, and deployment
• Analyzes spillover configuration effectiveness
• Reports request counts by status code
• Identifies peak throttling periods

Use Cases:

• Capacity planning for OpenAI deployments
• Troubleshooting throttling issues
• Optimizing deployment spillover configuration
• Monitoring API usage patterns

Output Columns:

• Subscription, Resource Group, Account Name
• Kind (OpenAI, Cognitive Services)
• SKU and deployment details
• Model name and spillover settings
• Hourly throttling statistics (status code, request count)

Data Source: Azure Monitor Metrics API (last 24-48 hours)

2. Carbon Emissions

Plugin Name: carbon-emissions
Command: azqr carbon-emissions
Flag: --plugin carbon-emissions
Version: 1.0.0

Analyzes carbon emissions by Azure resource type to support sustainability reporting and optimization.

Key Features:

• Tracks emissions by resource type across subscriptions
• Calculates month-over-month change ratios
• Aggregates emissions from multiple subscriptions
• Supports sustainability compliance reporting

Use Cases:

• Sustainability reporting and compliance
• Identifying high-emission resource types
• Tracking carbon reduction progress
• Environmental impact analysis

Output Columns:

• Period From/To (reporting period)
• Resource Type
• Latest Month Emissions
• Previous Month Emissions
• Month-over-Month Change Ratio
• Monthly Change Value
• Unit (metric tons CO2 equivalent)

Data Source: Azure Carbon Optimization API

3. Zone Mapping

Plugin Name: zone-mapping
Command: azqr zone-mapping
Flag: --plugin zone-mapping
Version: 1.0.0

Retrieves logical-to-physical availability zone mappings for all Azure regions in each subscription.

Key Features:

• Maps logical zones (1, 2, 3) to physical zone identifiers
• Reveals subscription-specific zone mappings
• Helps ensure proper zone alignment across subscriptions
• Supports multi-subscription architecture planning

Use Cases:

• Multi-subscription architecture design
• DR planning with zone awareness
• Zone alignment for latency optimization
• Compliance and audit documentation

Output Columns:

• Subscription, Location, Display Name
• Logical Zone (1, 2, or 3)
• Physical Zone (e.g., eastus-az1, westeurope-az2)

Data Source: Azure Resource Manager Subscriptions API

📖 Full Documentation

Usage

Running Internal Plugins

Internal plugins can be executed in two ways:

1. Standalone Plugin Commands (Recommended for Fast Execution)

Run plugins as top-level commands for optimized execution. This mode skips resource and APRL scanning, executing only the specified plugin:

# Run OpenAI throttling plugin
azqr openai-throttling

# Run carbon emissions plugin
azqr carbon-emissions

# Run zone mapping plugin
azqr zone-mapping

# Run with specific subscriptions
azqr zone-mapping --subscription-id <sub-id>

# Run with custom output name
azqr openai-throttling --output-name throttling-report

Benefits of Standalone Mode:

• ⚡ Faster execution - Skips resource scanning
• 📊 Cleaner reports - Contains only plugin results
• 🎯 Focused analysis - Dedicated to specific plugin output

2. Integrated with Full Scan

Run plugins alongside standard compliance scanning using the --plugin flag:

# Enable single plugin during scan
azqr scan --plugin openai-throttling

# Enable multiple plugins during scan
azqr scan --plugin openai-throttling --plugin carbon-emissions --plugin zone-mapping

# Combine with other scan options
azqr scan --subscription-id <sub-id> --plugin zone-mapping --output-name analysis

When to Use Scan Integration:

• Need both compliance recommendations and plugin analysis
• Want consolidated report with all data
• Running comprehensive assessments

Listing Available Plugins

View all registered plugins (internal and YAML):

azqr plugins list

Sample Output:

NAME                  VERSION    TYPE       DESCRIPTION
openai-throttling     1.0.0      internal   Checks OpenAI/Cognitive Services accounts for...
carbon-emissions      1.0.0      internal   Analyzes carbon emissions by Azure resource type
zone-mapping          1.0.0      internal   Retrieves logical-to-physical availability zone mappings...

Plugin Details

Get detailed information about a specific plugin:

azqr plugins info zone-mapping

Output Formats

Internal plugin results are included in all output formats:

Excel (Default)

Each internal plugin creates a dedicated worksheet in the Excel workbook:

• Zone Mapping sheet
• OpenAI Throttling sheet
• Carbon Emissions sheet

# Run plugins as standalone commands (fastest)
azqr openai-throttling
azqr carbon-emissions
azqr zone-mapping

# Or run with full scan
azqr scan --plugin openai-throttling --plugin carbon-emissions --plugin zone-mapping
# Generates: azqr_action_plan_YYYY_MM_DD_THHMMSS.xlsx

JSON

Plugin results are included in the pluginResults array:

# Run as standalone command
azqr zone-mapping --json

# Or run with full scan
azqr scan --plugin zone-mapping --json

JSON Structure:

{
  "recommendations": [...],
  "resources": [...],
  "pluginResults": [
    {
      "pluginName": "zone-mapping",
      "sheetName": "Zone Mapping",
      "description": "Retrieves logical-to-physical availability zone mappings for all Azure regions in each subscription",
      "table": [
        ["Subscription", "Location", "Display Name", "Logical Zone", "Physical Zone"],
        ["Production", "East US", "East US", "1", "eastus-az1"]
      ]
    }
  ]
}

CSV

Plugin results are exported to separate CSV files:

# Run as standalone command
azqr zone-mapping --csv

# Or run with full scan
azqr scan --plugin zone-mapping --csv
# Generates: 
#   <filename>.zone-mapping.csv
#   <filename>.recommendations.csv
#   <filename>.inventory.csv
#   ...

Interactive Dashboard

View plugin results interactively using the show command:

# Generate report with plugins (standalone commands)
azqr openai-throttling --output-name analysis
azqr carbon-emissions --output-name analysis
azqr zone-mapping --output-name analysis

# Or generate with full scan
azqr scan --plugin openai-throttling --plugin carbon-emissions --plugin zone-mapping --output-name analysis

# Launch interactive viewer
azqr show -f analysis.xlsx --open

The dashboard provides:

• Filterable columns (dropdowns, search)
• Sortable data tables
• Export capabilities
• Real-time filtering

Permissions

Internal plugins may require additional permissions beyond standard Reader access:

Recommended: Assign Reader and Monitoring Reader roles at subscription or management group scope.

Performance Considerations

Internal plugins add processing time to scans:

• openai-throttling: 1-3 minutes (depends on number of OpenAI accounts)
• carbon-emissions: 1-2 minutes (depends on subscription count)
• zone-mapping: <10 seconds (very fast, one API call per subscription)

Optimization Tips:

• Enable only needed plugins
• Use subscription/resource group filters to reduce scope

3 - Install

Install on Linux or Azure Cloud Shell

bash -c "$(curl -fsSL https://raw.githubusercontent.com/azure/azqr/main/scripts/install.sh)"

Install on Windows

Use winget:

winget install azqr

or download the executable file:

Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/azure/azqr/main/scripts/install.ps1'))

Install on Mac

Use homebrew:

brew install azqr

or download the latest release from here.

4 - Usage

Authorization

Azure Quick Review (azqr) requires the following permissions:

• Reader over Subscription or Management Group scope (required for all scans)

Authentication

Azure Quick Review (azqr) requires the following permissions:

• Reader over Subscription or Management Group scope

Credential Chain Configuration

Azure Quick Review (azqr) uses the Azure SDK’s DefaultAzureCredential which automatically selects the most appropriate credential based on your environment. By default, it tries credentials in order: environment variables, workload identity, managed identity, Azure CLI, and Azure Developer CLI.

You can customize this behavior by setting the AZURE_TOKEN_CREDENTIALS environment variable:

• dev - Prioritize Azure CLI (az) or Azure Developer CLI (azd) credentials (recommended for local development)
• prod - Prioritize environment variables, workload identity, or managed identity (recommended for CI/CD and production)

Service Principal Authentication

Set the following environment variables:

Powershell:

$env:AZURE_CLIENT_ID = '<service-principal-client-id>'
$env:AZURE_CLIENT_SECRET = '<service-principal-client-secret>'
$env:AZURE_TENANT_ID = '<tenant-id>'

Bash:

export AZURE_CLIENT_ID='<service-principal-client-id>'
export AZURE_CLIENT_SECRET='<service-principal-client-secret>'
export AZURE_TENANT_ID='<tenant-id>'

Authenticate with a Managed Identity

Set the following environment variables:

Powershell:

$env:AZURE_CLIENT_ID = '<managed-identity-client-id>'
$env:AZURE_TENANT_ID = '<tenant-id>'

Bash:

export AZURE_CLIENT_ID='<managed-identity-client-id>'
export AZURE_TENANT_ID='<tenant-id>'

Authenticate with Azure CLI

Authenticate to Azure:

az login

Cloud Configuration

Azure Quick Review (azqr) supports scanning resources in different Azure cloud environments. You can configure the target cloud using environment variables.

Predefined Cloud Environments

Set the AZURE_CLOUD environment variable to specify the Azure cloud environment:

Azure Public Cloud (default):

Powershell:

$env:AZURE_CLOUD = 'AzurePublic'

Bash:

export AZURE_CLOUD='AzurePublic'

Azure US Government Cloud:

Powershell:

$env:AZURE_CLOUD = 'AzureGovernment'

Bash:

export AZURE_CLOUD='AzureGovernment'

Azure China Cloud:

Powershell:

$env:AZURE_CLOUD = 'AzureChina'

Bash:

export AZURE_CLOUD='AzureChina'

Supported values for AZURE_CLOUD:

• AzurePublic, public, or empty (default)
• AzureGovernment, AzureUSGovernment, or usgovernment
• AzureChina or china

Custom Cloud Configuration

For custom or sovereign cloud environments, you can specify custom endpoints that will override the predefined cloud settings:

Powershell:

$env:AZURE_AUTHORITY_HOST = 'https://login.microsoftonline.custom/'
$env:AZURE_RESOURCE_MANAGER_ENDPOINT = 'https://management.custom.azure.com'
$env:AZURE_RESOURCE_MANAGER_AUDIENCE = 'https://management.core.custom.azure.com/'

Bash:

export AZURE_AUTHORITY_HOST='https://login.microsoftonline.custom/'
export AZURE_RESOURCE_MANAGER_ENDPOINT='https://management.custom.azure.com'
export AZURE_RESOURCE_MANAGER_AUDIENCE='https://management.core.custom.azure.com/'

Environment Variables:

• AZURE_AUTHORITY_HOST: Custom Active Directory authority host (e.g., https://login.microsoftonline.us/)
• AZURE_RESOURCE_MANAGER_ENDPOINT: Custom ARM endpoint (e.g., https://management.usgovcloudapi.net)
• AZURE_RESOURCE_MANAGER_AUDIENCE: Custom ARM token audience (optional, e.g., https://management.core.usgovcloudapi.net/)

Note: When custom endpoints are provided (both AZURE_AUTHORITY_HOST and AZURE_RESOURCE_MANAGER_ENDPOINT), they take priority over the AZURE_CLOUD setting.

Scan Azure Resources with default settings

• Scan All Resources

  azqr scan
  

• Scan a Management Group

  azqr scan --management-group-id <management_group_id>
  

• Scan a Subscription

  azqr scan --subscription-id <subscription_id>
  

• Scan a Resource Group

  azqr scan --subscription-id <subscription_id> --resource-group <resource_group_name>
  

• Scan Multiple Subscriptions

  azqr scan --subscription-id <sub_id_1> --subscription-id <sub_id_2>
  

• Scan Multiple Resource Groups

  azqr scan --subscription-id <sub_id> --resource-group <rg_1> --resource-group <rg_2>
  

Advanced Filtering

You can configure Azure Quick Review to include or exclude specific subscriptions or resource groups and also exclude services or recommendations. To do so, create a yaml file with the following format:

azqr:
  include:
    subscriptions:
      - <subscription_id> # format: <subscription_id>
    resourceGroups:
      - <resource_group_resource_id> # format: /subscriptions/<subscription_id>/resourceGroups/<resource_group_name>
    resourceTypes:
      - <resource type abbreviation> # format: Abbreviation of the resource type. For example: "vm" for "Microsoft.Compute/virtualMachines"
  exclude:
    subscriptions:
      - <subscription_id> # format: <subscription_id>
    resourceGroups:
      - <resource_group_resource_id> # format: /subscriptions/<subscription_id>/resourceGroups/<resource_group_name>
    services:
      - <service_resource_id> # format: /subscriptions/<subscription_id>/resourceGroups/<resource_group_name>/providers/<service_provider>/<service_name>
    recommendations:
      - <recommendation_id> # format: <recommendation_id>

Then run the scan with the --filters flag:

./azqr scan --filters <path_to_yaml_file>

Check the rules to get the recommendation ids.

Check the overview to get the resource type abbreviations.

Controlling Scan Stages

Azure Quick Review allows you to control which scan stages are executed. By default, diagnostics, advisor, and defender stages are enabled.

Available Stages

• advisor: Azure Advisor recommendations
• defender: Microsoft Defender for Cloud status
• defender-recommendations: Microsoft Defender for Cloud recommendations
• arc: Azure Arc-enabled SQL Server instances
• policy: Azure Policy compliance states
• cost: Cost analysis for the last 3 months
• diagnostics: Diagnostic settings scan

Stage Control Examples

# Enable specific stages (replaces defaults)
azqr scan --stages cost,policy

# Disable specific stages (keeps other defaults)
azqr scan --stages -diagnostics

# Enable all stages
azqr scan --stages advisor,defender,defender-recommendations,arc,policy,cost,diagnostics

Note: Use stage names with the - prefix to disable specific stages (e.g., -diagnostics).

Internal Plugins

Azure Quick Review includes specialized internal plugins for advanced analytics. Plugins can be run as standalone commands or integrated with full scans.

Running Plugins as Standalone Commands

For fast, focused analysis, run plugins as top-level commands:

# Run OpenAI throttling analysis
azqr openai-throttling

# Run carbon emissions analysis
azqr carbon-emissions

# Run zone mapping analysis
azqr zone-mapping

# With specific subscription
azqr zone-mapping --subscription-id <sub-id>

Integrating Plugins with Full Scans

Run plugins alongside standard scanning:

# Single plugin with scan
azqr scan --plugin openai-throttling

# Multiple plugins with scan
azqr scan --plugin openai-throttling --plugin carbon-emissions --plugin zone-mapping

# With other options
azqr scan --subscription-id <sub-id> --plugin zone-mapping

Listing Available Plugins

View all registered plugins:

azqr plugins list

View All Recommendations

You can list all available recommendations in markdown or JSON format:

# List recommendations as markdown table
azqr rules

# List recommendations as JSON
azqr rules --json

File Outputs

Currently Azure Quick Review supports 3 types of file outputs: xlsx (default), csv, json

xlsx

xlsx is the default output format.

Check the overview to get the more information.

csv

By default azqr will create an xlsx document, However if you need to export to csv you can use the following flag: --csv

Example:

azqr scan --csv

- json

By default azqr will create an xlsx document, However if you need to export to json you can use the following flag: --json

Example:

azqr scan --json

The scan will generate a single consolidated json file:

<file-name>.json

Changing the Output File Name

You can change the output file name by using the --output-name or -o flag:

Powershell:

$timestamp = Get-Date -Format 'yyyyMMddHHmmss'
azqr scan --output-name "azqr_action_plan_$timestamp"

Bash:

timestamp=$(date '+%Y%m%d%H%M%S')
azqr scan --output-name "azqr_action_plan_$timestamp"

By default, the output file name is azqr_action_plan_YYYY_MM_DD_THHMMSS.

Output to STDOUT

You can output JSON results directly to stdout:

# Output JSON to stdout
azqr scan --json --stdout

Masking Subscription IDs

By default, Azure Quick Review masks subscription IDs in reports for security. You can control this behavior:

# Disable masking (show full subscription IDs)
azqr scan --mask=false

# Enable masking explicitly (default)
azqr scan --mask=true

Interactive Dashboard (show command)

You can explore your scan results with a lightweight embedded web UI using the show command. The dashboard supports both Excel and JSON report formats.

Usage

1. Generate a report (Excel or JSON):

# Excel format (default)
azqr scan --subscription-id <subscription_id> --output-name report

# JSON format
azqr scan --subscription-id <subscription_id> --output-name report --json

2. Launch the dashboard:

# With Excel file
azqr show --file report.xlsx --open

# With JSON file
azqr show --file report.json --open

# On custom port
azqr show --file report.xlsx --port 3000

MCP Server (Model Context Protocol)

Azure Quick Review includes a Model Context Protocol (MCP) server that enables AI assistants and tools to interact with azqr functionality. The MCP server can run in two modes:

stdio Mode (Default)

The stdio mode is designed for integration with tools like VS Code and AI assistants that communicate via standard input/output:

# Start MCP server in stdio mode
azqr mcp

This mode is typically used when azqr is configured as an MCP server in your IDE or AI assistant configuration.

HTTP/SSE Mode

The HTTP/SSE (Server-Sent Events) mode allows the MCP server to be accessed over HTTP, enabling remote access and web-based integrations:

# Start MCP server in HTTP mode on default port (:8080)
azqr mcp --mode http

# Start MCP server on a custom port
azqr mcp --mode http --addr :3000

# Start with specific host and port
azqr mcp --mode http --addr localhost:9090

Debugging and Troubleshooting

Debug Mode

Azure Quick Review supports a global --debug flag for troubleshooting. This flag is available for all commands:

# Enable debug logging for scan
azqr scan --debug

# Enable debug logging for plugins
azqr zone-mapping --debug
azqr openai-throttling --debug

# Combine with other flags
azqr scan --subscription-id <sub-id> --debug --stages cost

Full Diagnostic Output

For comprehensive troubleshooting, combine environment variables with the debug flag:

# Enable full debugging output
export AZURE_SDK_GO_LOGGING=all
azqr scan --debug

Common Issues

If you encounter any issue while using Azure Quick Review (azqr):

1. Enable debug mode with --debug flag
2. Set AZURE_SDK_GO_LOGGING=all environment variable
3. Run the command and capture the output
4. Share the console output by filing a new issue

Help

You can get help for azqr commands by running:

azqr --help

5 - Recommendations

Azure Quick Review checks the following recommendations for Azure resources. The recommendations are categorized based on their impact and category:

## Recommendations List

Total Supported Azure Resource Types: 105

6 - Troubleshooting & Support

If you encounter any issue while using Azure Quick Review (azqr), please set the AZURE_SDK_GO_LOGGING environment variable to all, run the tool with the --debug flag and then share the console output with us by filing a new issue.

Support

This project uses GitHub Issues to track bugs and feature requests. Before logging an issue please check 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.

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

7 - Contribution Guidelines

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repositories using our CLA.

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.

Contributing to Documentation

Below are the steps and required packages to get the Azure Quick Review Hugo site to build and run locally.

• Ensure that you have the following packages installed locally.

  • git
  • hugo extended
  • nodejs

• Fork the azqr repository, clone locally and then head to the docs folder

  cd .\azqr\docs
  

• Execute the Node Module installer

  npm install
  

• Once this has finish you can execute the Hugo Server

  hugo server
  

8 - Resources & References

Microsoft Documentation

• Azure Well-Architected Framework
• Azure Availability Zones
• Azure Service Level Agreements
• Azure Diagnostic Settings
• Azure Private Link
• Azure Advisor
• Microsoft Defender for Cloud
• Azure Cost Management + Billing

Related Projects

• Azure Proactive Resiliency Library (APRL)
• Azure Orphan Resources
• review-checklist
• PSRule.Rules.Azure

9 - Related Projects

AZQR and APRL

As of version 2.0.0-preview, Azure Quick Review (azqr) includes all Azure Resource Graph queries provided by the the Azure Proactive Resiliency Library (APRL), which are used to identify non-compliant resources.

Azure Quick Review (azqr) extends APRL by providing per service instance SLAs, Diagnostic Settings detection and more. Therefore, scan results display AZQR or APRL, to indicate the source of the recommendation.

APRL provides a curated catalog of resiliency recommendations for workloads running in Azure. Many of the recommendations contain supporting Azure Resource Graph (ARG) queries

AZQR and Azure Orphan Resources

As of version 2.4.0 Azure Quick Review (azqr) includes all Azure Resource Graph queries provided by the the Azure Orphan Resources project

AZQR compared to Azure Review Checklists and PSRule.Rules.Azure

Azure Quick Review (azqr) was created to address a very specific need we had back in 2022. Initially, we had to run three assessments to get a clear picture of various solutions in terms of SLAs, use of Availability Zones, and Diagnostic Settings. At the time, we were not aware of the existence of the review-checklist or PSRule.Rules.Azure.

When some of our peers saw the assessments we were able to deliver with the early bits of Azure Quick Review (azqr), they asked us to add more checks (recommendations) and change the output format from markdown to Excel.

As many of our customers work in restrictive environments, the ability to run a self-contained, cross-platform binary while using read-only permissions became a key feature.

Moving forward to 2023, based on great feedback from both peers and customers, we moved the original repo to the Azure organization, added support for more services, and fixed various issues.

In August 2024, we added all APRL recommendations to Azure Quick Review (azqr) and removed duplicates in favor of the ones already available as Azure Resource Graph queries.

When compared with PSRule.Rules.Azure, Azure Quick Review (azqr) only scans deployed Azure resources and provides recommendations based on the current state. Azure Quick Review (azqr) does not scan ARM templates or Bicep files.

When compared to the review-checklist, Azure Quick Review (azqr) also provides an actionable list of more than 400 recommendations (70+ Azure resource types), that can be used to improve the resiliency of your Azure solutions.

10 - Profiling azqr

Overview

azqr includes built-in profiling capabilities that allow you to capture:

• CPU Profile: Identifies where your program spends most of its CPU time
• Memory Profile: Shows heap allocations and memory usage patterns
• Execution Trace: Provides detailed information about goroutine scheduling, garbage collection, and system calls

Note: Profiling features are only available in debug builds to keep production binaries lightweight and secure.

Building Debug Version

To use profiling features, you must build azqr with the debug build tag:

# Build debug version with profiling support
make debug

# This creates: bin/linux_arm64/azqr-debug (or appropriate OS/arch)

The debug build includes:

• CPU profiling (--cpu-profile)
• Memory profiling (--mem-profile)
• Execution trace profiling (--trace-profile)
• Debug logging and additional instrumentation

Profiling Commands

Basic Profiling

To enable profiling, use the new flags with the debug version of azqr scan:

# CPU profiling
azqr-debug scan --subscription-id "your-sub-id" --cpu-profile cpu.prof

# Memory profiling  
azqr-debug scan --subscription-id "your-sub-id" --mem-profile mem.prof

# Execution trace profiling
azqr-debug scan --subscription-id "your-sub-id" --trace-profile trace.prof

# Combined profiling (recommended for comprehensive analysis)
azqr-debug scan --subscription-id "your-sub-id" \
  --cpu-profile cpu.prof \
  --mem-profile mem.prof \
  --trace-profile trace.prof

Note: Replace azqr-debug with the actual path to your debug binary, e.g., ./bin/linux_arm64/azqr-debug

Analyzing Profile Data

Prerequisites

Install Go profiling tools:

go install github.com/google/pprof@latest

Optional: Install Graphviz for visual call graphs

# Ubuntu/Debian
sudo apt-get install graphviz

# macOS
brew install graphviz

# Windows (using chocolatey)
choco install graphviz

# Or download from: https://graphviz.org/download/

Note: Graphviz is only required for generating visual call graphs (PNG, SVG) and web-based graph views. The core profiling analysis works without it.

CPU Profile Analysis

# Interactive analysis (no Graphviz required)
go tool pprof cpu.prof

# Web interface (recommended - no Graphviz required)
go tool pprof -http=:8080 cpu.prof

# Generate call graph (requires Graphviz)
go tool pprof -png cpu.prof > cpu_profile.png
go tool pprof -svg cpu.prof > cpu_profile.svg

# Show top 10 functions consuming CPU (no Graphviz required)
go tool pprof -top cpu.prof

# Text-based call graph (no Graphviz required)
go tool pprof -text cpu.prof

Key CPU Metrics to Look For:

• Functions with high cumulative time (including called functions)
• Functions with high flat time (excluding called functions)
• Hot spots in Azure SDK calls
• Expensive operations in scanners

Memory Profile Analysis

# Interactive memory analysis (no Graphviz required)
go tool pprof mem.prof

# Web interface for memory (no Graphviz required)
go tool pprof -http=:8081 mem.prof

# Show memory allocations (no Graphviz required)
go tool pprof -alloc_space mem.prof

# Show objects in memory (no Graphviz required)
go tool pprof -inuse_objects mem.prof

# Generate memory allocation graph (requires Graphviz)
go tool pprof -png -alloc_space mem.prof > mem_alloc.png

Key Memory Metrics:

• alloc_space: Total memory allocated during execution
• alloc_objects: Total number of objects allocated
• inuse_space: Memory currently in use
• inuse_objects: Number of objects currently in use

Execution Trace Analysis

# View trace in web browser (no Graphviz required)
go tool trace trace.prof

Trace Analysis Views:

• Goroutine analysis: Shows goroutine lifecycle and blocking
• Network blocking profile: Network I/O bottlenecks
• Synchronization blocking profile: Mutex and channel contention
• Syscall blocking profile: System call performance
• Scheduler latency profile: Goroutine scheduling delays

Working Without Graphviz

If you don’t have Graphviz installed, you can still perform comprehensive profiling analysis:

Alternative Analysis Commands

# Text-based top functions
go tool pprof -text -cum cpu.prof | head -20

# Text-based call graph
go tool pprof -text cpu.prof

# Interactive command-line interface
go tool pprof cpu.prof
# Then use commands: top, list, web (if available), quit

# Web interface (works without Graphviz for most features)
go tool pprof -http=:8080 cpu.prof
# Note: Some graph views may not work, but tables and flamegraphs will

Performance Optimization Strategies

Based on Profiling Results

1. CPU Optimization

• High JSON Processing: Consider streaming parsers for large responses
• Expensive Reflection: Cache reflection operations
• HTTP Client Overhead: Implement connection pooling
• Azure SDK Calls: Batch API calls where possible

2. Memory Optimization

• Large Object Allocations: Use object pooling for frequently allocated objects
• String Concatenations: Use strings.Builder or pre-allocated buffers
• Slice Growth: Pre-allocate slices with known capacity
• Memory Leaks: Ensure proper cleanup of resources and references

3. Concurrency Optimization

• Goroutine Pools: Limit concurrent operations to prevent resource exhaustion
• Channel Buffering: Use appropriately sized buffered channels
• Context Timeouts: Implement proper timeout handling
• Rate Limiting: Respect Azure API rate limits

Red Flags

• Memory usage growing continuously (memory leaks)
• High GC pressure (> 50% CPU time in GC)
• Excessive goroutine creation (> 10,000 goroutines)
• Long-running HTTP requests without proper timeouts

Contributing Performance Improvements

When submitting performance optimizations:

1. Include before/after profiling data
2. Provide benchmark results
3. Document the optimization approach
4. Ensure no functionality regressions

Run make test to ensure all tests pass after performance optimizations.