Edit

Custom compliance discovery scripts for Microsoft Intune

Before you can use custom settings for compliance with Microsoft Intune, you must create a script that discovers custom compliance settings on devices. The script you use depends on the platform:

  • Windows devices use a PowerShell script.
  • Linux devices can run scripts in any language as long as the corresponding interpreter is installed and configured on the device.

The discovery script deploys to devices as part of your custom compliance policies. When compliance runs on a device, the script discovers the settings defined in the JSON file you provide when creating the compliance policy.

All discovery scripts:

  • Are added to Intune before you create a compliance policy. After you add a script, it's available to select when you create a compliance policy with custom settings.
    • Each discovery script can only be used with one compliance policy, and each compliance policy can only include one discovery script.
    • You can't delete discovery scripts that are assigned to a compliance policy until you unassign the script from the policy.
  • Run on a device that receives the compliance policy. The script evaluates the conditions of the JSON file you upload when creating a custom compliance policy.
  • Identify one or more settings, as defined in the JSON, and return a list of discovered values for those settings.

In addition, the PowerShell script for Windows:

  • Must be compressed to output results in a single line. For example, the following script must include return $hash | ConvertTo-Json -Compress as the last line:

    $hash = @{ Manufacturer = $WMI_ComputerSystem.Manufacturer; BiosVersion = $WMI_BIOS.SMBIOSBIOSVersion; TPMChipPresent = $TPM.TPMPresent}
return $hash | ConvertTo-Json -Compress

Limits

To successfully return compliance data to Intune, your scripts must stay within the following limits:

  • Scripts can be no larger than 1 megabyte (MB) each.
  • Output generated by each script can be no larger than 1 MB.
  • Scripts must have a limited run time:
    • On Linux, scripts must take five minutes or less to run.
    • On Windows, scripts must take 10 minutes or less to run.

Sample discovery script for Windows

The following example is a sample PowerShell script that you can use for Windows devices:

$WMI_ComputerSystem = Get-WMIObject -class Win32_ComputerSystem
$WMI_BIOS = Get-WMIObject -class Win32_BIOS
$TPM = Get-Tpm

$hash = @{ Manufacturer = $WMI_ComputerSystem.Manufacturer; BiosVersion = $WMI_BIOS.SMBIOSBIOSVersion; TPMChipPresent = $TPM.TPMPresent}
return $hash | ConvertTo-Json -Compress

The following example shows the output of the sample script for Windows:

{"BiosVersion":"1.24","Manufacturer":"Microsoft Corporation","TPMChipPresent":true}

Sample discovery script for Linux

Note

On Linux, discovery scripts run in the user's context. They can't check for system-level settings that require elevation. An example of this limitation is the state/hash of the /etc/sudoers file.

Discovery scripts for Linux can call any interpreter that meets your requirements. Ensure that the chosen interpreter is properly installed and configured on the target device before deploying the script. To specify the interpreter for a script, include a shebang line at the top of the script, indicating the path to the interpreter binary.

For example, if your script should use the Bash shell as the interpreter, add the following line at the top of your script:

#!/bin/bash

To use Python, specify the interpreter path. For example, add the following line to the top of your script: #!/usr/bin/python3 or #!/usr/bin/env python3

Tip

To handle interrupts or cancellation signals, implement graceful termination mechanisms in your scripts. When a script handles these signals, it can perform cleanup tasks and exit gracefully, ensuring resources are released correctly. For example, catch signals like SIGINT (interrupt signal) or SIGTERM (termination signal) and define custom actions to run when they're received. These actions can include closing open files, releasing acquired locks, or cleaning up temporary resources.

For more information, see the Intune Linux Custom Compliance Samples guide.

Add a discovery script to Intune

Before deploying your script in production, test it in an isolated environment to ensure the syntax you use behaves as expected.

Note

The script upload workflow doesn't support scope tags. You must be assigned the default scope tag to create, edit, or view custom compliance discovery scripts.

  1. Sign in to the Microsoft Intune admin center and go to Endpoint security > Device compliance > Scripts > Add. Then choose your platform.

  2. On Basics, enter a descriptive Name for the script.

  3. On Settings, add your script to Detection script. Review your script carefully. Intune doesn't validate the script for syntax or programming errors.

  4. For Windows only - On Settings, configure the following behavior for the PowerShell script:

    • Run this script using the logged on credentials – By default, the script runs in the System context on the device. Set this value to Yes to have it run in the context of the logged-on user. If the user isn't logged in, the script defaults back to the System context.
    • Enforce script signature check – For more information, see about_Signing in the PowerShell documentation.
    • Run script in 64 bit PowerShell Host – By default, the script runs using the 32-bit PowerShell host. Set this value to Yes to force the script to run using the 64-bit host instead.

  5. Complete the script creation process. The script appears in the Scripts pane and is available to select when configuring compliance policies.

Next steps

  • Last updated on