Get compliance data of Azure resources
One of the largest benefits of Azure Policy is the insight and controls it provides over resources in a subscription or management group of subscriptions. This control can prevent resources from being created in the wrong location, enforce common and consistent tag usage, or audit existing resources for appropriate configurations and settings. In all cases, Azure Policy generates data that enables you to understand the compliance state of your environment.
Before reviewing compliance data, it's important to understand compliance states in Azure Policy.
There are several ways to access the compliance information generated by your policy and initiative assignments:
Before looking at the methods to report on compliance, let's look at when compliance information is updated and the frequency and events that trigger an evaluation cycle.
Evaluation triggers
The results of a completed evaluation cycle are available in the Microsoft.PolicyInsights Resource Provider through PolicyStates and PolicyEvents operations. For more information about the operations of the Azure Policy Insights REST API, see Azure Policy Insights.
Evaluations of assigned policies and initiatives happen as the result of various events:
- A policy or initiative is newly assigned to a scope. It takes about five minutes for the assignment to be applied to the defined scope, then the evaluation cycle begins for applicable resources against the newly assigned policy or initiative. Depending on the effects used, resources are marked as compliant, non-compliant, exempt, or unknown. A large policy or initiative evaluated against a large scope of resources can take time, so there's no predefined expectation of when the evaluation cycle completes. After it completes, updated compliance results are available in the portal and Software Development Kits (SDKs).
- A policy or initiative already assigned to a scope is updated. The evaluation cycle and timing for this scenario is the same as for a new assignment to a scope.
- A resource is deployed to or updated within a scope with an assignment via Azure Resource Manager, REST API, or a supported SDK. In this scenario, the effect event (append, audit, deny, deploy) and compliant status information for the individual resource becomes available in the portal and SDKs around 15 minutes later. This event doesn't cause an evaluation of other resources.
- A subscription (resource type
Microsoft.Resources/subscriptions) is created or moved within a management group hierarchy with an assigned policy definition targeting the subscription resource type. Evaluation of the subscription supported effects (audit, auditIfNotExist, deployIfNotExists, modify), logging, and any remediation actions takes around 30 minutes. - A policy exemption is created, updated, or deleted. In this scenario, the corresponding assignment is evaluated for the defined exemption scope.
- Standard compliance evaluation cycle. Once every 24 hours, assignments are automatically reevaluated. A large policy or initiative of many resources can take time, so there's no predefined expectation of when the evaluation cycle completes. Once it completes, updated compliance results are available in the portal and SDKs.
- The machine configuration resource provider is updated with compliance details by a managed resource.
- On-demand scan.
Note
By design, Azure Policy exempts from policy evaluation all resources under the Microsoft.Resources resource provider except for subscriptions and resource groups, which can be evaluated.
On-demand evaluation scan
An evaluation scan for a subscription or a resource group can be started with REST, Azure CLI, Azure PowerShell, Azure Policy extension for Visual Studio Code, or Azure Policy Compliance Scan GitHub Action. The on-demand scans are an asynchronous process that takes a long time to run because resources are evaluated against all assigned policies.
Note
Not all Azure resource providers support on-demand evaluation scans. For example, Azure Virtual Network Manager (AVNM) currently doesn't support either manual triggers or the standard policy compliance evaluation cycle (daily scans).
On-demand evaluation scan using REST
As an asynchronous process, the REST endpoint to start the scan doesn't wait until the scan is complete to respond. Instead, it provides a URI to query the status of the requested evaluation.
In each REST API URI, there are variables that are used that you need to replace with your own values:
{resourceGroupName}: Replace with the name of your resource group.{subscriptionId}: Replace with your subscription ID.
The scan supports evaluation of resources in a subscription or in a resource group. Start a scan by scope with a REST API POST command using the following URI structures:
Use the following command to evaluate a subscription. You can run the command from your browser at Policy States - Trigger Subscription Evaluation using the Try it option.
POST https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.PolicyInsights/policyStates/latest/triggerEvaluation?api-version=2019-10-01
Use the following command to evaluate a resource group. You can run the command from your browser at Policy States - Trigger Resource Group Evaluation using the Try it option.
POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.PolicyInsights/policyStates/latest/triggerEvaluation?api-version=2019-10-01
The subscription and resource group REST API calls return a 202 Accepted status. Included in the response header is a location property with the following format:
https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.PolicyInsights/asyncOperationResults/{ResourceContainerGUID}?api-version=2019-10-01
{ResourceContainerGUID} is statically generated for the scope requested. If a scope is already running an on-demand scan, a new scan isn't started. Instead, the new request is provided the same {ResourceContainerGUID} location URI for status. A REST API GET command to the location URI returns a 202 Accepted while the evaluation is ongoing. When the evaluation scan is complete, it returns a 200 OK status. The body of a completed scan is a JSON response with the status: succeeded.
On-demand evaluation scan using Azure CLI
The compliance scan is started with the az policy state trigger-scan command.
By default, az policy state trigger-scan starts an evaluation for all resources in the current subscription. To start an evaluation on a specific resource group, use the resource-group parameter. The following example starts a compliance scan in the current subscription for a resource group. Replace resourceGroupName with your resource group's name:
az policy state trigger-scan --resource-group "resourceGroupName"
You can choose not to wait for the asynchronous process to complete before continuing with the no-wait parameter.
On-demand evaluation scan using Azure PowerShell
The compliance scan is started with the Start-AzPolicyComplianceScan cmdlet.
By default, Start-AzPolicyComplianceScan starts an evaluation for all resources in the current subscription. To start an evaluation on a specific resource group, use the ResourceGroupName parameter. The following example starts a compliance scan in the current subscription for a resource group. Replace resourceGroupName with your resource group's name:
Start-AzPolicyComplianceScan -ResourceGroupName 'resourceGroupName'
You can have PowerShell wait for the asynchronous call to complete before providing the results output or have it run in the background as a job. To use a PowerShell job to run the compliance scan in the background, use the AsJob parameter and set the value to an object, such as $job in this example:
$job = Start-AzPolicyComplianceScan -AsJob
You can check on the status of the job by checking on the $job object. The job is of the type Microsoft.Azure.Commands.Common.AzureLongRunningJob. Use Get-Member on the $job object to see available properties and methods.
While the compliance scan is running, checking the $job object outputs results such as these:
$job
Id Name PSJobTypeName State HasMoreData Location Command
-- ---- ------------- ----- ----------- -------- -------
2 Long Running O... AzureLongRunni... Running True localhost Start-AzPolicyCompliance...
When the compliance scan completes, the State property changes to Completed.
On-demand evaluation scan using Visual Studio Code
The Azure Policy extension for Visual Studio Code is capable of running an evaluation scan for a specific resource. This scan is a synchronous process, unlike the Azure PowerShell and REST methods. For details and steps, see On-demand evaluation with the VS Code extension.
On-demand evaluation scan using GitHub Actions
Use the Azure Policy Compliance Scan action to trigger an on-demand evaluation scan from your GitHub workflow on one or multiple resources, resource groups, or subscriptions, and gate the workflow based on the compliance state of resources. You can also configure the workflow to run at a scheduled time so that you get the latest compliance status at a convenient time. Optionally, GitHub Actions can generate a report on the compliance state of scanned resources for further analysis or for archiving.
The following example runs a compliance scan for a subscription. In scopes use your subscription ID.
on:
schedule:
- cron: '0 8 * * *' # runs every morning 8am
jobs:
assess-policy-compliance:
runs-on: ubuntu-latest
steps:
- name: Login to Azure
uses: azure/login@v2
with:
creds: ${{secrets.AZURE_CREDENTIALS}}
- name: Check for resource compliance
uses: azure/policy-compliance-scan@v0
with:
scopes: |
/subscriptions/aaaa6a6a-bb7b-cc8c-dd9d-eeeeee0e0e0e
For more information and workflow samples, see the GitHub Actions for Azure Policy Compliance Scan repo.
Portal
The Azure portal showcases a graphical experience of visualizing and understanding the state of compliance in your environment. On the Policy page, the Overview option provides details for available scopes on the compliance of both policies and initiatives. Along with the compliance state and count per assignment, it contains a chart showing compliance over the last seven days. The Compliance page contains much of this same information (except the chart), but provides more filtering and sorting options.
Since a policy or initiative can be assigned to different scopes, the table includes the scope for each assignment and the type of definition that was assigned. The number of non-compliant resources and non-compliant policies for each assignment are also provided. Selecting on a policy or initiative in the table provides a deeper look at the compliance for that particular assignment.
The list of resources on the Resource compliance tab shows the evaluation status of existing resources for the current assignment. The tab defaults to Non-compliant, but can be filtered. Events (append, audit, deny, deploy, modify) triggered by the request to create a resource are shown under the Events tab.
For Resource Provider mode resources, on the Resource compliance tab, selecting the resource or right-clicking on the row and selecting View compliance details opens the component compliance details. This page also offers tabs to see the policies that are assigned to this resource, events, component events, and change history.
Back on the resource compliance page, select and hold (or right-click) on the row of the event you would like to gather more details on and select Show activity logs. The activity log page opens and is prefiltered to the search showing details for the assignment and the events. The activity log provides more context and information about those events.
Note
Compliance results can be exported from the portal with Azure Resource Graph queries.
Command line
The same information available in the portal can be retrieved with the REST API, Azure CLI, and Azure PowerShell.
REST API
For details about the REST API, see the Azure Policy reference. The REST API reference pages have a Try It option on each operation that allows you to run the command in a browser. You can also use Azure CLI or your preferred REST API client to run commands.
Summarize results
With the REST API, you can summarize by container, definition, or assignment. Here's an example of summarization at the subscription level using Azure Policy Insight's Summarize For Subscription:
POST https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.PolicyInsights/policyStates/latest/summarize?api-version=2019-10-01
The output summarizes the subscription, and the summarized compliance are in the nonCompliantResources and nonCompliantPolicies properties. This request provides other details, including each assignment that made up the non-compliant numbers and the definition information for each assignment. Each policy object in the hierarchy provides a queryResultsUri that can be used to get more detail at that level.
Query for resources
In the previous example, value.policyAssignments.policyDefinitions.results.queryResultsUri provides a sample URI for all non-compliant resources for a specific policy definition. In the $filter value, ComplianceState is equal (eq) to NonCompliant, PolicyAssignmentId is specified for the policy definition, and then the PolicyDefinitionId itself. The reason for including the PolicyAssignmentId in the filter is because the PolicyDefinitionId could exist in several policy or initiative assignments with different scopes. By specifying both the PolicyAssignmentId and the PolicyDefinitionId, we can be explicit in the results we're looking for. Previously, for PolicyStates we used latest, which automatically sets a from and to time window of the last 24-hours.
Example of the queryResultsUri value:
https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.PolicyInsights/policyStates/latest/queryResults?api-version=2019-10-01&$from=2025-01-01 04:28:22Z&$to=2025-02-10 04:28:22Z&$filter=ComplianceState eq 'NonCompliant' and PolicyAssignmentId eq '/subscriptions/{subscriptionId}/resourcegroups/rg-tags/providers/microsoft.authorization/policyassignments/37ce239ae4304622914f0c77' and PolicyDefinitionId eq '/providers/microsoft.authorization/policydefinitions/1e30110a-5ceb-460c-a204-c1c3969c6d62'
View events
When a resource is created or updated, a policy evaluation result is generated. Results are called policy events. Use the following URI to view recent policy events associated with the subscription.
https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.PolicyInsights/policyEvents/default/queryResults?api-version=2019-10-01
For more information about querying policy events, see Azure Policy Events.
Azure CLI
The Azure CLI command group for Azure Policy covers most operations that are available in REST or Azure PowerShell. For the full list of available commands, see az policy.
Get the state summary for the topmost assigned policy with the highest number of non-compliant resources.
az policy state summarize --top 1
Get the state record for the most recently evaluated resource and the output default is by timestamp in descending order.
az policy state list --top 1
Get the details for all non-compliant virtual network resources.
az policy state list --filter "ResourceType eq 'Microsoft.Network/virtualNetworks'"
Get events related to non-compliant virtual network resources that occurred after a specific date. Use the from parameter with a date in ISO 8601 format.
az policy event list --filter "ResourceType eq 'Microsoft.Network/virtualNetworks'" --from '2025-02-10T00:00:00Z'
Azure PowerShell
You can run the following commands from Azure Cloud Shell.
Get the state summary for the topmost assigned policy with the highest number of non-compliant resources.
Get-AzPolicyStateSummary -Top 1
Get the state record for the most recently evaluated resource. The output default is by timestamp in descending order.
Get-AzPolicyState -Top 1
Get the details for all non-compliant virtual network resources.
Get-AzPolicyState -Filter "ResourceType eq '/Microsoft.Network/virtualNetworks'"
Get events related to non-compliant virtual network resources that occurred after a specific date. Use the From parameter with a date in ISO 8601 format.
Get-AzPolicyEvent -Filter "ResourceType eq '/Microsoft.Network/virtualNetworks'" -From '2025-02-10'
The output includes a PrincipalOid property that can be used to get a specific user with the Azure PowerShell cmdlet Get-AzADUser. Replace {principalOid} with the value you get from the previous command.
(Get-AzADUser -ObjectId {principalOid}).DisplayName
Azure Monitor logs
If you have a Log Analytics workspace with AzureActivity from the Activity Log Analytics solution tied to your subscription, you can also view non-compliance results from the evaluation of new and updated resources using Kusto queries and the AzureActivity table. With details in Azure Monitor logs, alerts can be configured to watch for non-compliance.
Azure Resource Graph
Compliance records are stored in Azure Resource Graph (ARG). Data can be exported from ARG queries to form customized dashboards based on the scopes and policies of interest. Review our sample queries for exporting compliance data through ARG.
Next steps
- Review examples at Azure Policy samples.
- Review the Azure Policy definition structure.
- Review Understanding policy effects.
- Understand how to programmatically create policies.
- Learn how to remediate non-compliant resources.
- Review what a management group is with Organize your resources with Azure management groups.