Understand Azure Policy's Guest Configuration
In addition to auditing and remediating Azure resources, Azure Policy can audit settings inside a virtual machine. The validation is performed by the Guest Configuration extension and client. The extension, through the client, validates settings such as the configuration of the operating system, application configuration or presence, environment settings, and more.
This article has been updated to use the new Azure PowerShell Az module. You can still use the AzureRM module, which will continue to receive bug fixes until at least December 2020. To learn more about the new Az module and AzureRM compatibility, see Introducing the new Azure PowerShell Az module. For Az module installation instructions, see Install Azure PowerShell.
Extension and client
To audit settings inside a virtual machine, a virtual machine extension is enabled. The extension downloads applicable policy assignment and the corresponding configuration definition.
Register Guest Configuration resource provider
Before you can use Guest Configuration, you must register the resource provider. You can register through the portal or through PowerShell. The resource provider is registered automatically if assignment of a Guest Configuration policy is done through the portal.
Registration - Portal
To register the resource provider for Guest Configuration through the Azure portal, follow these steps:
Launch the Azure portal and click on All services. Search for and select Subscriptions.
Find and click on the subscription that you want to enable Guest Configuration for.
In the left menu of the Subscription page, click Resource providers.
Filter for or scroll until you locate Microsoft.GuestConfiguration, then click Register on the same row.
Registration - PowerShell
To register the resource provider for Guest Configuration through PowerShell, run the following command:
# Login first with Connect-AzAccount if not using Cloud Shell Register-AzResourceProvider -ProviderNamespace 'Microsoft.GuestConfiguration'
Inside the virtual machine, the Guest Configuration client uses local tools to run the audit.
The following table shows a list of the local tools used on each supported operating system:
|Operating system||Validation tool||Notes|
|Windows||Microsoft Desired State Configuration v2|
|Linux||Chef InSpec||Ruby and Python are installed by the Guest Configuration extension.|
The Guest Configuration client checks for new content every 5 minutes. Once a guest assignment is received, the settings are checked on a 15-minute interval. Results are sent to the Guest Configuration resource provider as soon as the audit completes. When a policy evaluation trigger occurs, the state of the machine is written to the Guest Configuration resource provider. This causes Azure Policy to evaluate the Azure Resource Manager properties. An on-demand Azure Policy evaluation retrieves the latest value from the Guest Configuration resource provider. However, it doesn't trigger a new audit of the configuration within the virtual machine.
Supported client types
The following table shows a list of supported operating system on Azure images:
|Canonical||Ubuntu Server||14.04, 16.04, 18.04|
|Microsoft||Windows Server||2012 Datacenter, 2012 R2 Datacenter, 2016 Datacenter, 2019 Datacenter|
|Microsoft||Windows Client||Windows 10|
|OpenLogic||CentOS||7.3, 7.4, 7.5|
|Red Hat||Red Hat Enterprise Linux||7.4, 7.5|
Guest Configuration can audit nodes running a supported OS. If you would like to audit virtual machines that use a custom image, you need to duplicate the DeployIfNotExists definition and modify the If section to include your image properties.
Unsupported client types
Windows Server Nano Server is not supported in any version.
Guest Configuration Extension network requirements
To communicate with the Guest Configuration resource provider in Azure, virtual machines require outbound access to Azure datacenters on port 443. If you're using a private virtual network in Azure and don't allow outbound traffic, exceptions must be configured using Network Security Group rules. At this time, a service tag doesn't exist for Azure Policy Guest Configuration.
For IP address lists, you can download Microsoft Azure Datacenter IP Ranges. This file is updated weekly, and has the currently deployed ranges and any upcoming changes to the IP ranges. You only need to allow outbound access to the IPs in the regions where your VMs are deployed.
The Azure Datacenter IP address XML file lists the IP address ranges that are used in the Microsoft Azure datacenters. The file includes compute, SQL, and storage ranges. An updated file is posted weekly. The file reflects the currently deployed ranges and any upcoming changes to the IP ranges. New ranges that appear in the file aren't used in the datacenters for at least one week. It's a good idea to download the new XML file every week. Then, update your site to correctly identify services running in Azure. Azure ExpressRoute users should note that this file is used to update the Border Gateway Protocol (BGP) advertisement of Azure space in the first week of each month.
Guest Configuration definition requirements
Each audit run by Guest Configuration requires two policy definitions, a DeployIfNotExists definition and an Audit definition. The DeployIfNotExists definition is used to prepare the virtual machine with the Guest Configuration agent and other components to support the validation tools.
The DeployIfNotExists policy definition validates and corrects the following items:
- Validate the virtual machine has been assigned a configuration to evaluate. If no assignment is currently present, get the assignment and prepare the virtual machine by:
If the DeployIfNotExists assignment is Non-compliant, a remediation task can be used.
Once the DeployIfNotExists assignment is Compliant, the Audit policy assignment uses the local validation tools to determine if the configuration assignment is Compliant or Non-compliant. The validation tool provides the results to the Guest Configuration client. The client forwards the results to the Guest Extension, which makes them available through the Guest Configuration resource provider.
Azure Policy uses the Guest Configuration resource providers complianceStatus property to report compliance in the Compliance node. For more information, see getting compliance data.
The DeployIfNotExists policy is required for the Audit policy to return results. Without the DeployIfNotExists, the Audit policy shows "0 of 0" resources as status.
All built-in policies for Guest Configuration are included in an initiative to group the definitions for use in assignments. The built-in initiative named [Preview]: Audit Password security settings inside Linux and Windows virtual machines contains 18 policies. There are six DeployIfNotExists and Audit pairs for Windows and three pairs for Linux. In each case, the logic inside the definition validates only the target operating system is evaluated based on the policy rule definition.
Guest Configuration policies currently only support assigning the same Guest Assignment once per virtual machine, even if the Policy assignment uses different parameters.
Client log files
The Guest Configuration extension writes log files to the following locations:
<version> refers to the current version number.
Guest Configuration samples
Samples for Policy Guest Configuration are available in the following locations:
- 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 get compliance data.
- Learn how to remediate non-compliant resources.
- Review what a management group is with Organize your resources with Azure management groups.