By: Jack Davis – Sr. Product Manager | Microsoft Endpoint Manager – Intune
With the recent general availability of custom compliance, customers now have the ability to further define what device compliance means for their organization's managed Windows devices. Custom compliance uses a PowerShell script and an associated JSON file to define one or more rules. The process works like this:
The PowerShell script runs on a device to discover and report on the settings defined in the JSON file.
Then, the JSON file defines the acceptable values for those settings.
Depending on your custom compliance script complexity, manually building a JSON file to evaluate your discovery script results can be an error prone process. It’s critical that the associated JSON file is properly formatted for use in Intune and matches the defined Key/Value pairs. We’ve written a PowerShell module that makes this process easier and less error prone which this blog will cover.
In this example we’ll create a single custom compliance rule based on 8 remote assistance Firewall Rules, resulting in 116 lines of JSON required for the rule. We’ll use the Firewall Rules “Name” and “Action” properties to define both the discovery (PowerShell script) and the acceptable values in our detection JSON.
Figure 2: A screenshot of the Create custom script setup in Intune to create the Firewall rule detection script.
Once the discovery script has been defined and uploaded, we then create the detection JSON file. To assist with this, leverage the Intune custom compliance module available in the PowerShell Gallery (refer to the file path below). This module requires PowerShell 6.1 or above.
New-IntuneCustomComplianceSetting - for use with properly formatting a single rule setting. This cmdlet will provide the JSON export required for upload into Microsoft Endpoint Manager.
New-IntuneCustomComplianceRuleSet - to accept multiple Key/Value pairs defined in a single custom compliance policy. This cmdlet then outputs and transforms each setting and its value into a single JSON ruleset that can be imported into Microsoft Endpoint Manager.
For this scenario, we’ll use New-IntuneCustomComplianceRuleSet since our example contains multiple Key/Value pairs. To begin, ensure the query results output to a variable ($qr), as detailed in our discovery script above. Be sure to select the object property Key/Value pair to be used in the custom compliance rule. We will select Name and Action as our chosen properties.
Figure 3: The output query script showing Name and Action values.
The query results can now be used with the New-IntuneCustomComplianceRuleSet cmdlet. Use the Destination parameter to output the JSON file, as shown below. The Action property will output as an integer when converted to JSON.
Figure 4: The custom compliance JSON file created by the IntuneCustomCompliance cmdlet using the Destination parameter.
After you’ve run the cmdlet and automated the creation of your JSON file, you’ll need to upload it in Microsoft Endpoint Manager admin center. Before proceeding, ensure you have already uploaded the discovery script you’ve defined to work alongside the newly created JSON file. Create your new compliance policy by navigating to Endpoint security > Device compliance > Create policy (Windows 10 and later) in the admin center. From the Custom compliance drop-down, select the associated discovery script and then import your newly created JSON file.
Figure 5: A screenshot of the Compliance policy settings Custom Compliance options.
After you've successfully imported your JSON file, a preview of it will display each rule in a table (see the example below). Complete setting up the compliance rule to prepare for deployment.
Figure 6: A screenshot of the setting rules that appear after the JSON file is uploaded in Custom compliance settings.
Once deployed, your compliance results for the newly created compliance rule can be displayed in Per-setting status. Your setup is complete.
Figure 7: A screenshot of the Per-setting status page showing the Firewall Rule settings configured using the steps outlined in this document and that there are four devices compliant with each setting.
In our example above, we automated the manual effort involved in creating the 116-line JSON detection file and formatted it to easily import it into Intune.
Figure 8: A snippet of the Custom Compliance JSON file that includes custom Firewall rules.
Using custom compliance opens a world of opportunity to increase your organization’s security posture. Use the IntuneCustomCompliance PowerShell module to easily craft complex JSON detection with minimal effort, saving you time to focus on enhancing security.
If you have any questions or comments for the Intune team, reply to this post or reach out to @IntuneSuppTeam on Twitter.