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 be exercised in many different ways, such as preventing resources being created in the wrong location, enforcing common and consistent tag usage, or auditing existing resources for appropriate configurations and settings. In all cases, data is generated by Azure Policy to enable you to understand the compliance state of your environment.

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.

Warning

If compliance state is being reported as Not registered, verify that the Microsoft.PolicyInsights Resource Provider is registered and that the user has the appropriate role-based access control (RBAC) permissions as described in RBAC in Azure Policy.

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 around 30 minutes for the assignment to be applied to the defined scope. Once it's applied, the evaluation cycle begins for resources within that scope against the newly assigned policy or initiative and depending on the effects used by the policy or initiative, resources are marked as compliant or non-compliant. A large policy or initiative evaluated against a large scope of resources can take time. As such, there's no pre-defined expectation of when the evaluation cycle will complete. Once it completes, updated compliance results are available in the portal and 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 a scope with an assignment via Resource Manager, REST, Azure CLI, or Azure PowerShell. 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.

  • 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 pre-defined expectation of when the evaluation cycle will complete. Once it completes, updated compliance results are available in the portal and SDKs.

  • The Guest Configuration resource provider is updated with compliance details by a managed resource.

  • On-demand scan

On-demand evaluation scan

An evaluation scan for a subscription or a resource group can be started with a call to the REST API. This scan is an asynchronous process. As such, 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:

  • {YourRG} - 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:

  • Subscription

    POST https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.PolicyInsights/policyStates/latest/triggerEvaluation?api-version=2018-07-01-preview
    
  • Resource group

    POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{YourRG}/providers/Microsoft.PolicyInsights/policyStates/latest/triggerEvaluation?api-version=2018-07-01-preview
    

The call returns 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=2018-07-01-preview

{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 has completed, it returns a 200 OK status. The body of a completed scan is a JSON response with the status:

{
    "status": "Succeeded"
}

How compliance works

In an assignment, a resource is Non-compliant if it doesn't follow policy or initiative rules. The following table shows how different policy effects work with the condition evaluation for the resulting compliance state:

Resource state Effect Policy evaluation Compliance state
Exists Deny, Audit, Append*, DeployIfNotExist*, AuditIfNotExist* True Non-compliant
Exists Deny, Audit, Append*, DeployIfNotExist*, AuditIfNotExist* False Compliant
New Audit, AuditIfNotExist* True Non-compliant
New Audit, AuditIfNotExist* False Compliant

* The Append, DeployIfNotExist, and AuditIfNotExist effects require the IF statement to be TRUE. The effects also require the existence condition to be FALSE to be non-compliant. When TRUE, the IF condition triggers evaluation of the existence condition for the related resources.

For example, assume that you have a resource group – ContsoRG, with some storage accounts (highlighted in red) that are exposed to public networks.

Storage accounts exposed to public networks

In this example, you need to be wary of security risks. Now that you've created a policy assignment, it's evaluated for all storage accounts in the ContosoRG resource group. It audits the three non-compliant storage accounts, consequently changing their states to Non-compliant.

Audited non-compliant storage accounts

Besides Compliant and Non-compliant, policies and resources have three other states:

  • Conflicting: Two or more policies exist with conflicting rules. For example, two policies appending the same tag with different values.
  • Not started: The evaluation cycle hasn't started for the policy or resource.
  • Not registered: The Azure Policy Resource Provider hasn't been registered or the account logged in doesn't have permission to read compliance data.

Azure Policy uses the type and name fields in the definition to determine if a resource is a match. When the resource matches, it's considered applicable and has a status of either Compliant or Non-compliant. If either type or name is the only property in the definition, then all resources are considered applicable and are evaluated.

The compliance percentage is determined by dividing Compliant resources by total resources. Total resources is defined as the sum of the Compliant, Non-compliant, and Conflicting resources. The overall compliance numbers are the sum of distinct resources that are Compliant divided by the sum of all distinct resources. In the image below, there are 20 distinct resources that are applicable and only one is Non-compliant. The overall resource compliance is 95% (19 out of 20).

Example of policy compliance from Compliance page

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 provide additional filtering and sorting options.

Example of Azure Policy Compliance page

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. Clicking on a policy or initiative in the table provides a deeper look at the compliance for that particular assignment.

Example of Azure Policy Compliance Details page

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) triggered by the request to create a resource are shown under the Events tab.

Note

For an AKS Engine policy, the resource shown is the resource group.

Example of Azure Policy Compliance events

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.

Example of Azure Policy Component compliance details

Back on the resource compliance page, 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 pre-filtered to the search showing details for the assignment and the events. The activity log provides additional context and information about those events.

Example of Azure Policy Compliance Activity Log

Understand non-compliance

When a resources is determined to be non-compliant, there are many possible reasons. To determine the reason a resource is non-compliant or to find the change responsible, see Determine non-compliance.

Command line

The same information available in the portal can be retrieved with the REST API (including with ARMClient), Azure PowerShell, and Azure CLI (preview). For full details on the REST API, see the Azure Policy Insights reference. The REST API reference pages have a green 'Try It' button on each operation that allows you to try it right in the browser.

Use ARMClient or a similar tool to handle authentication to Azure for the REST API examples.

Summarize results

With the REST API, summarization can be performed by container, definition, or assignment. Here is 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=2018-04-04

The output summarizes the subscription. In the example output below, the summarized compliance are under value.results.nonCompliantResources and value.results.nonCompliantPolicies. This request provides further 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 additional detail at that level.

{
    "@odata.context": "https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.PolicyInsights/policyStates/$metadata#summary",
    "@odata.count": 1,
    "value": [{
        "@odata.id": null,
        "@odata.context": "https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.PolicyInsights/policyStates/$metadata#summary/$entity",
        "results": {
            "queryResultsUri": "https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.PolicyInsights/policyStates/latest/queryResults?api-version=2018-04-04&$from=2018-05-18 04:28:22Z&$to=2018-05-19 04:28:22Z&$filter=IsCompliant eq false",
            "nonCompliantResources": 15,
            "nonCompliantPolicies": 1
        },
        "policyAssignments": [{
            "policyAssignmentId": "/subscriptions/{subscriptionId}/resourcegroups/rg-tags/providers/microsoft.authorization/policyassignments/37ce239ae4304622914f0c77",
            "policySetDefinitionId": "",
            "results": {
                "queryResultsUri": "https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.PolicyInsights/policyStates/latest/queryResults?api-version=2018-04-04&$from=2018-05-18 04:28:22Z&$to=2018-05-19 04:28:22Z&$filter=IsCompliant eq false and PolicyAssignmentId eq '/subscriptions/{subscriptionId}/resourcegroups/rg-tags/providers/microsoft.authorization/policyassignments/37ce239ae4304622914f0c77'",
                "nonCompliantResources": 15,
                "nonCompliantPolicies": 1
            },
            "policyDefinitions": [{
                "policyDefinitionReferenceId": "",
                "policyDefinitionId": "/providers/microsoft.authorization/policydefinitions/1e30110a-5ceb-460c-a204-c1c3969c6d62",
                "effect": "deny",
                "results": {
                    "queryResultsUri": "https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.PolicyInsights/policyStates/latest/queryResults?api-version=2018-04-04&$from=2018-05-18 04:28:22Z&$to=2018-05-19 04:28:22Z&$filter=IsCompliant eq false 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'",
                    "nonCompliantResources": 15
                }
            }]
        }]
    }]
}

Query for resources

In the example above, value.policyAssignments.policyDefinitions.results.queryResultsUri provides a sample Uri for all non-compliant resources for a specific policy definition. Looking at the $filter value, IsCompliant is equal (eq) to false, 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.

https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.PolicyInsights/policyStates/latest/queryResults?api-version=2018-04-04&$from=2018-05-18 04:28:22Z&$to=2018-05-19 04:28:22Z&$filter=IsCompliant eq false 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'

The example response below has been trimmed to a single non-compliant resource for brevity. The detailed response has several pieces of data about the resource, the policy or initiative, and the assignment. Notice that you can also see what assignment parameters were passed to the policy definition.

{
    "@odata.context": "https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.PolicyInsights/policyStates/$metadata#latest",
    "@odata.count": 15,
    "value": [{
        "@odata.id": null,
        "@odata.context": "https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.PolicyInsights/policyStates/$metadata#latest/$entity",
        "timestamp": "2018-05-19T04:41:09Z",
        "resourceId": "/subscriptions/{subscriptionId}/resourceGroups/rg-tags/providers/Microsoft.Compute/virtualMachines/linux",
        "policyAssignmentId": "/subscriptions/{subscriptionId}/resourceGroups/rg-tags/providers/Microsoft.Authorization/policyAssignments/37ce239ae4304622914f0c77",
        "policyDefinitionId": "/providers/Microsoft.Authorization/policyDefinitions/1e30110a-5ceb-460c-a204-c1c3969c6d62",
        "effectiveParameters": "",
        "isCompliant": false,
        "subscriptionId": "{subscriptionId}",
        "resourceType": "/Microsoft.Compute/virtualMachines",
        "resourceLocation": "westus2",
        "resourceGroup": "RG-Tags",
        "resourceTags": "tbd",
        "policyAssignmentName": "37ce239ae4304622914f0c77",
        "policyAssignmentOwner": "tbd",
        "policyAssignmentParameters": "{\"tagName\":{\"value\":\"costCenter\"},\"tagValue\":{\"value\":\"Contoso-Test\"}}",
        "policyAssignmentScope": "/subscriptions/{subscriptionId}/resourceGroups/RG-Tags",
        "policyDefinitionName": "1e30110a-5ceb-460c-a204-c1c3969c6d62",
        "policyDefinitionAction": "deny",
        "policyDefinitionCategory": "tbd",
        "policySetDefinitionId": "",
        "policySetDefinitionName": "",
        "policySetDefinitionOwner": "",
        "policySetDefinitionCategory": "",
        "policySetDefinitionParameters": "",
        "managementGroupIds": "",
        "policyDefinitionReferenceId": ""
    }]
}

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=2018-04-04

Your results resemble the following example:

{
    "@odata.context": "https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.PolicyInsights/policyEvents/$metadata#default",
    "@odata.count": 1,
    "value": [{
        "@odata.id": null,
        "@odata.context": "https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.PolicyInsights/policyEvents/$metadata#default/$entity",
        "NumAuditEvents": 16
    }]
}

For more information about querying policy events, see the Azure Policy Events reference article.

Azure PowerShell

The Azure PowerShell module for Azure Policy is available on the PowerShell Gallery as Az.PolicyInsights. Using PowerShellGet, you can install the module using Install-Module -Name Az.PolicyInsights (make sure you have the latest Azure PowerShell installed):

# Install from PowerShell Gallery via PowerShellGet
Install-Module -Name Az.PolicyInsights

# Import the downloaded module
Import-Module Az.PolicyInsights

# Login with Connect-AzAccount if not using Cloud Shell
Connect-AzAccount

The module has the following cmdlets:

  • Get-AzPolicyStateSummary
  • Get-AzPolicyState
  • Get-AzPolicyEvent
  • Get-AzPolicyRemediation
  • Remove-AzPolicyRemediation
  • Start-AzPolicyRemediation
  • Stop-AzPolicyRemediation

Example: Getting the state summary for the topmost assigned policy with the highest number of non-compliant resources.

PS> Get-AzPolicyStateSummary -Top 1

NonCompliantResources : 15
NonCompliantPolicies  : 1
PolicyAssignments     : {/subscriptions/{subscriptionId}/resourcegroups/RG-Tags/providers/micros
                        oft.authorization/policyassignments/37ce239ae4304622914f0c77}

Example: Getting the state record for the most recently evaluated resource (default is by timestamp in descending order).

PS> Get-AzPolicyState -Top 1

Timestamp                  : 5/22/2018 3:47:34 PM
ResourceId                 : /subscriptions/{subscriptionId}/resourceGroups/RG-Tags/providers/Mi
                             crosoft.Network/networkInterfaces/linux316
PolicyAssignmentId         : /subscriptions/{subscriptionId}/resourceGroups/RG-Tags/providers/Mi
                             crosoft.Authorization/policyAssignments/37ce239ae4304622914f0c77
PolicyDefinitionId         : /providers/Microsoft.Authorization/policyDefinitions/1e30110a-5ceb-460c-a204-c1c3969c6d62
IsCompliant                : False
SubscriptionId             : {subscriptionId}
ResourceType               : /Microsoft.Network/networkInterfaces
ResourceLocation           : westus2
ResourceGroup              : RG-Tags
ResourceTags               : tbd
PolicyAssignmentName       : 37ce239ae4304622914f0c77
PolicyAssignmentOwner      : tbd
PolicyAssignmentParameters : {"tagName":{"value":"costCenter"},"tagValue":{"value":"Contoso-Test"}}
PolicyAssignmentScope      : /subscriptions/{subscriptionId}/resourceGroups/RG-Tags
PolicyDefinitionName       : 1e30110a-5ceb-460c-a204-c1c3969c6d62
PolicyDefinitionAction     : deny
PolicyDefinitionCategory   : tbd

Example: Getting the details for all non-compliant virtual network resources.

PS> Get-AzPolicyState -Filter "ResourceType eq '/Microsoft.Network/virtualNetworks'"

Timestamp                  : 5/22/2018 4:02:20 PM
ResourceId                 : /subscriptions/{subscriptionId}/resourceGroups/RG-Tags/providers/Mi
                             crosoft.Network/virtualNetworks/RG-Tags-vnet
PolicyAssignmentId         : /subscriptions/{subscriptionId}/resourceGroups/RG-Tags/providers/Mi
                             crosoft.Authorization/policyAssignments/37ce239ae4304622914f0c77
PolicyDefinitionId         : /providers/Microsoft.Authorization/policyDefinitions/1e30110a-5ceb-460c-a204-c1c3969c6d62
IsCompliant                : False
SubscriptionId             : {subscriptionId}
ResourceType               : /Microsoft.Network/virtualNetworks
ResourceLocation           : westus2
ResourceGroup              : RG-Tags
ResourceTags               : tbd
PolicyAssignmentName       : 37ce239ae4304622914f0c77
PolicyAssignmentOwner      : tbd
PolicyAssignmentParameters : {"tagName":{"value":"costCenter"},"tagValue":{"value":"Contoso-Test"}}
PolicyAssignmentScope      : /subscriptions/{subscriptionId}/resourceGroups/RG-Tags
PolicyDefinitionName       : 1e30110a-5ceb-460c-a204-c1c3969c6d62
PolicyDefinitionAction     : deny
PolicyDefinitionCategory   : tbd

Example: Getting events related to non-compliant virtual network resources that occurred after a specific date.

PS> Get-AzPolicyEvent -Filter "ResourceType eq '/Microsoft.Network/virtualNetworks'" -From '2018-05-19'

Timestamp                  : 5/19/2018 5:18:53 AM
ResourceId                 : /subscriptions/{subscriptionId}/resourceGroups/RG-Tags/providers/Mi
                             crosoft.Network/virtualNetworks/RG-Tags-vnet
PolicyAssignmentId         : /subscriptions/{subscriptionId}/resourceGroups/RG-Tags/providers/Mi
                             crosoft.Authorization/policyAssignments/37ce239ae4304622914f0c77
PolicyDefinitionId         : /providers/Microsoft.Authorization/policyDefinitions/1e30110a-5ceb-460c-a204-c1c3969c6d62
IsCompliant                : False
SubscriptionId             : {subscriptionId}
ResourceType               : /Microsoft.Network/virtualNetworks
ResourceLocation           : eastus
ResourceGroup              : RG-Tags
ResourceTags               : tbd
PolicyAssignmentName       : 37ce239ae4304622914f0c77
PolicyAssignmentOwner      : tbd
PolicyAssignmentParameters : {"tagName":{"value":"costCenter"},"tagValue":{"value":"Contoso-Test"}}
PolicyAssignmentScope      : /subscriptions/{subscriptionId}/resourceGroups/RG-Tags
PolicyDefinitionName       : 1e30110a-5ceb-460c-a204-c1c3969c6d62
PolicyDefinitionAction     : deny
PolicyDefinitionCategory   : tbd
TenantId                   : {tenantId}
PrincipalOid               : {principalOid}

The PrincipalOid field can be used to get a specific user with the Azure PowerShell cmdlet Get-AzADUser. Replace {principalOid} with the response you get from the previous example.

PS> (Get-AzADUser -ObjectId {principalOid}).DisplayName
Trent Baker

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 cycle using simple Kusto queries and the AzureActivity table. With details in Azure Monitor logs, alerts can be configured to watch for non-compliance.

Azure Policy Compliance using Azure Monitor logs

Next steps