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.
If you’re not yet familiar with Intune custom compliance, please review Use custom compliance settings in Microsoft Intune before proceeding.
Example walkthrough
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.
Discovery script
$hash = @{}
$qr = Get-NetFirewallRule | Where-Object {($PSItem.Direction -eq 'Inbound') -and ($PSitem.Name -like '*RemoteAssistance*') -and ($PSitem.Name -notlike '*query*')} | Select-Object Name, Action
foreach ($rule in $qr) {
$hash.Add($rule.Name, [int64]($rule.Action.value__))
}
return $hash | ConvertTo-Json -Compress
To validate our code, the output of the above script should resemble the compressed format in the snippet below.
The script can then be added to Intune by following the guidance in Custom PowerShell scripts for discovery.
Detection JSON
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.
PS C:\> Find-Module IntuneCustomCompliance | Install-Module
The module consists of 2 cmdlets:
- 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.
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.
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.
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.
Once deployed, your compliance results for the newly created compliance rule can be displayed in Per-setting status. Your setup is complete.
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.
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.