Create Discovery Scripts for Custom Compliance Policy in Microsoft Intune - Microsoft Intune | Microsoft Learn
In brief
The page received editorial updates, including title capitalization, wording, links, and formatting. The Windows instructions no longer list the 64-bit PowerShell host setting.
What Intune admins need to know
Review the updated Windows script guidance when creating or maintaining custom compliance discovery scripts.
This summary was assembled from the tracked documentation change. Verify important details in the full Microsoft Learn article.
Documentation change
The comparison below shows only the changed extract. Use the full-page view for complete context.
Create discovery scriptsDiscovery Scripts for custom compliance policyCustom Compliance Policy in Microsoft Intune - Microsoft Intune | Microsoft Learn
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:
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.
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 macOS, scripts must take 10 minutes or less to run.
- On Windows, scripts must take 10 minutes or less to run.
Note
On Linux, discovery scripts run in theyour 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.
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..
Sample discovery script for macOS
Discovery scripts for macOS use Bash and must include a valid shebang line (for example,line, such as #!/bin/bash). Scripts must be UTF-8 encoded without BOM, and must return exit code 0 for success and a non-zero exit code for failure.
The following example returns the version of the Microsoft Intune Agent app installed on the device:
Add a discovery script to Intune
Before deployingyou deploy your script in production, test it in an isolated environment to ensure the syntax you use behaves as expected.
Sign
intoin to Microsoft Intune admin center and go to Endpoint security > Device compliance > Scripts > Add > (choose your platform).On Basics, provide a Name.
On Settings, add your script to Detection script. Review your script carefully. Intune doesn’t validate the script for syntax or programmatic errors.
For macOS - On Settings, configure the following behavior for the Bash script:
- Run this script using the logged on credentials
–. Set this value to Yes to run the script in the context of the logged-on user. - Enforce script signature check
–. Set this value to Yes to require a valid signature on the script. - Hide script notifications on devices
–. Set this value to Yes to hide notifications from the script on the device.
For Windows only
-: On Settings, configure the following behavior for the PowerShell script:- Run this script using the logged on credentials
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.
-
- Enforce script signature check
–. For more information, see about_Signingin 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.
\ No newline at end of file
- 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.
-
5. Complete the script creation process. The script appears in the Scripts pane and is available to select when configuring compliance policies.
\ No newline at end of file
\ No newline at end of file
@@ -1,6 +1,6 @@ --- layout: Conceptual-title: Create discovery scripts for custom compliance policy in Microsoft Intune - Microsoft Intune | Microsoft Learn+title: Create Discovery Scripts for Custom Compliance Policy in Microsoft Intune - Microsoft Intune | Microsoft Learn canonicalUrl: https://learn.microsoft.com/en-us/intune/device-security/compliance/create-custom-script author: ilwu-microsoft ms.author: ilwu@@ -14,7 +14,7 @@ ms.collection: - sub-device-compliance ms.subservice: protect description: Create scripts for Linux, macOS, or Windows devices to discover the settings you define as custom compliance settings for Microsoft Intune.-ms.date: 2025-09-04T00:00:00.0000000Z+ms.date: 2026-11-11T00:00:00.0000000Z ms.topic: concept-article ms.reviewer: ilwu locale: en-us@@ -45,7 +45,7 @@ spProducts: platformId: 37a723c2-5b25-64af-cc30-3e45e43df0c7 --- -# Create discovery scripts for custom compliance policy in Microsoft Intune - Microsoft Intune | Microsoft Learn+# Create Discovery Scripts for Custom Compliance Policy in Microsoft Intune - Microsoft Intune | Microsoft Learn Before you can use [custom settings for compliance](custom-settings) with Microsoft Intune, you must create a script that discovers custom compliance settings on devices. The script you use depends on the platform:
@@ -58,6 +58,7 @@ The discovery script deploys to devices as part of your custom compliance polici 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.
@@ -79,6 +80,7 @@ To successfully return compliance data to Intune, your scripts must stay within - 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 macOS, scripts must take 10 minutes or less to run.
- On Windows, scripts must take 10 minutes or less to run.
@@ -106,7 +108,7 @@ The following example shows the output of the sample script for Windows:
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.
+On Linux, discovery scripts run in your user 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.
@@ -120,11 +122,11 @@ 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](https://github.com/microsoft/shell-intune-samples/tree/master/Linux) guide.
+For more information, see [Intune Linux Custom Compliance Samples](https://github.com/microsoft/shell-intune-samples/tree/master/Linux).
## Sample discovery script for macOS
-Discovery scripts for macOS use Bash and must include a valid shebang line (for example, `#!/bin/bash`). Scripts must be UTF-8 encoded without BOM, and must return exit code 0 for success and a non-zero exit code for failure.
+Discovery scripts for macOS use Bash and must include a valid shebang line, such as `#!/bin/bash`. Scripts must be UTF-8 encoded without BOM, and must return exit code 0 for success and a non-zero exit code for failure.
The following example returns the version of the Microsoft Intune Agent app installed on the device:
@@ -144,25 +146,24 @@ fi
## 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.
+Before you deploy your script in production, test it in an isolated environment to ensure the syntax you use behaves as expected.
-1. Sign into [Microsoft Intune admin center](https://go.microsoft.com/fwlink/?linkid=2109431) and go to **Endpoint security** > **Device compliance** > **Scripts** > **Add** > *(choose your platform)*.
+1. Sign in to [Microsoft Intune admin center](https://go.microsoft.com/fwlink/?linkid=2109431) and go to **Endpoint security** > **Device compliance** > **Scripts** > **Add** > *(choose your platform)*.
2. On **Basics**, provide a **Name**.
3. On **Settings**, add your script to **Detection script**. Review your script carefully. Intune doesn’t validate the script for syntax or programmatic errors.
4. ***For macOS*** - On **Settings**, configure the following behavior for the Bash script:
- - **Run this script using the logged on credentials** – Set this value to **Yes** to run the script in the context of the logged-on user.
- - **Enforce script signature check** – Set this value to **Yes** to require a valid signature on the script.
- - **Hide script notifications on devices** – Set this value to **Yes** to hide notifications from the script on the device.
+ - **Run this script using the logged on credentials**. Set this value to **Yes** to run the script in the context of the logged-on user.
+ - **Enforce script signature check**. Set this value to **Yes** to require a valid signature on the script.
+ - **Hide script notifications on devices**. Set this value to **Yes** to hide notifications from the script on the device.
- ***For Windows only*** - On **Settings**, configure the following behavior for the PowerShell script:
-
-Note
+ ***For Windows only***: On **Settings**, configure the following behavior for the PowerShell script:
-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.
+ Note
-- **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](/en-us/powershell/module/microsoft.powershell.core/about/about_signing?view=powershell-7.1&preserve-view=true) 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.
+ 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. Complete the script creation process. The script appears in the **Scripts** pane and is available to select when configuring compliance policies.\ No newline at end of file+ - **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](/en-us/powershell/module/microsoft.powershell.core/about/about_signing?view=powershell-7.1&preserve-view=true).
+ - **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.\ No newline at end of file