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 are check to see if the device full fill all compliance requirements from your company like a min OS Version. In the past there was some pre defined policies from Microsoft which you can use, With the service release 2208 there was added the support for custom compliance checks where you can freely query everything on the device. This 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. One is a JSON and one is a detection script. The Json file defines the custom settings and the values that are considered as compliant. This json can also contain a message for the user how to restore the compliance. The script it to query the the check on the device and return 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 in two sub topics in PowerShell and json. In this sections I will show you how you can create the PowerShell and the json but I will provide you much more examples in my git hub repository.


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.


The json describes how to deal with the output. This is the more complicated thing but lets also check this step by step but if you need more information check this link.

The json is build out of an array of rules. If you have only one rule the array contains only one entry but if you have multiple return values from the script link in our example you can add also 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 an knowledge base article, blog or info page how to solve the issue or to get more information about.
  • RemediationString: This is an array with the message/s. You can write messages in en_Us only or und multiple languages.

Here is the example for the fitting json for our PowerShell script:

    "Rules": [
            "SettingName": "AvActive",
            "Operator": "IsEquals",
            "DataType": "Boolean",
            "Operand": true,
            "MoreInfoUrl": "",
            "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": "",
            "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 in the script field and check if the script should be run with logged on credentials or in 64bit 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 of the device is noncompliant. Default is to mark the device as noncompliant but you can e.g. also send an email to the user
  • Create a assignment. In my case it is all devices
  • Click Next -> Create

Where can I find the repository with examples

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

5 thoughts on “How to use Custom Compliance Script + Example script

  1. Fits straight to what we need right now! Thanks!

    Maybe you like to have look to your GitHub repository and check Check-IfDeviceIsEncrypted. It seems it contains the wrong script.


  2. Hi Jannik, thanks for this. This is great
    How can I add a variable from PowerShell to the description in json? something like below. Whats the right syntax?

    “Description”: “The device has only $freestorage. Please run a cleanup to have minimum of 10gb”


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s