How to use Custom Compliance Script + Example script

Compliance policies are essential for ensuring that devices meet all the necessary requirements set by the company, such as a minimum OS version. Previously, Microsoft provided predefined policies that could be used, but with the service release 2208, support for custom compliance checks was added, enabling the freedom to query everything on the device what you want. In this blog post, we will focus on how to create custom compliance policies for Windows.

What are custom compliance policy

Compliance policies check whether a device fulfills all compliance requirements from your company, such as a minimum OS version. In the past there were some predefined policies from Microsoft that you could use. With the service release 2208 support for custom compliance checks was added, allowing you to freely query anything on the device. These custom compliance policies are supported on Windows and Linux. In this blog we will focus on the Windows custom compliance policies.

To create a custom compliance policy you need two things: a JSON file and a detection script. The JSON file defines the custom settings and the values that are considered compliant. This JSON can also contain a message for the user on how to restore compliance. The script queries the check on the device and returns the value when a compliance policy is evaluated. The script will be executed via the sidecar agent.

How to write a compliance script

We will split this section into two subtopics: PowerShell and JSON. In this section I will show you how to create the PowerShell and the JSON, but I provide many more examples in my GitHub repository.

PowerShell

In the PowerShell script you have all the freedom that PowerShell offers you. The output must be a JSON. This output JSON can contain several checks. Here is an example script:

$avActive = $false
if(Get-CimInstance -Namespace root/SecurityCenter2 -ClassName AntiVirusProduct){
    $avActive = $true
}

$freeStorage = [math]::Round((Get-PSDrive -Name C).Free / 1024 / 1024 / 1024)
$output = @{ AvActive = $avActive; FreeStorage = $freeStorage}
return $output | ConvertTo-Json -Compress

This script checks if an AV is activated and returns the free storage in GB.

Json

The JSON describes how to deal with the output. This is the more complicated part, but let us check it step by step. If you need more information, check this link.

The JSON is built from an array of rules. If you have only one rule the array contains a single entry, but if you have multiple return values from the script (like in our example) you can also add multiple rules.

Each rule has to contain the following attributes:

• SettingName: Name of the json tag from the PowerShell output
• DataType: The data type of the output. Possible values are: Boolean, Int64, Double, String, DateTime, Version
• Operator: The operator for the check. Possible values are: IsEquals, NotEquals, GreaterThan, GreaterEquals, LessThan, LessEquals
• MoreInfoURL: Here you can define a URL to a knowledge base article, blog, or info page on how to solve the issue or to get more information.
• RemediationString: This is an array of messages. You can write messages in en_US only or in multiple languages.

Here is the matching JSON for our PowerShell script:

{
    "Rules": [
        {
            "SettingName": "AvActive",
            "Operator": "IsEquals",
            "DataType": "Boolean",
            "Operand": true,
            "MoreInfoUrl": "https://google.com",
            "RemediationStrings": [
                {
                    "Language": "en_US",
                    "Title": "This machine has no active antivirus solution.",
                    "Description": "To continue to use this device you have to install a Antivirus Solution"
                }
            ]
        },
        {
            "SettingName": "FreeStorage",
            "Operator": "GreaterEquals",
            "DataType": "int64",
            "Operand": 10,
            "MoreInfoUrl": "https://google.com",
            "RemediationStrings": [
                {
                    "Language": "en_US",
                    "Title": "No storage free.",
                    "Description": "The device has less than 10GB storage free. Please run a cleanup"
                }
            ]
        }
    ]
}

How to define the policy in Intune

Add the script

• Open the intune admin center
• Navigate to Devices -> Compliance policies -> Scripts
• Select Windows 10 and later

• Enter a Name
• Click Next

• Copy the script into the script field and decide whether the script should run with logged-on credentials or in 64-bit context
• Click Next -> Create

Define the compliance policy

• Navigate to Devices -> Compliance Policies -> New Policy
• Click +Create policy
• Select Windows 10 and later as Platform and click Create

• Enter a name for the policy
• Click Next

• Select Custom Compliance and set this to Required
• Select Click to select and select the previous created script
• Click Select

• Click on the folder icon to upload the definition json from your filesystem
• Check if your conditions are correct
• Click Next

• Select the action for when the device is noncompliant. The default is to mark the device as noncompliant, but you can, for example, also send an email to the user

• Create an assignment. In my case it is all devices
• Click Next -> Create

Where can I find the repository with examples

I have created a GitHub repository with some example scripts. If you have more ideas for scripts or if you want to create a pull request, feel free to reach out to me.