Automatically run scripts

Fleet v4.58.0 introduces the ability to execute scripts on hosts automatically based on predefined policy failures. This guide will walk you through configuring Fleet to automatically execute scripts on hosts using uploaded scripts based on programmed policies.

Fleet allows users to upload scripts executed on macOS, Windows, and Linux hosts to remediate issues with those hosts. These scripts can now be automated to run when a policy fails. Learn more about scripts here.

Prerequisites

• fleetd deployed with the --enable-scripts flag. If you're using MDM features, scripts are enabled by default.

Step-by-step instructions

1. Add a script: Navigate to Controls > Scripts, select the team on which you want the script and policy to run, and upload the script you want to run.
2. Add a policy: Navigate to Policies, select the team you want the policy to run on, and click Add policy. Follow the instructions to set up a custom policy or use one baked into Fleet. You can also add a script automation to an existing policy.
3. Set the automation: In the previous step's Policies list view you navigated to, click Manage automations, then click Run script. Check the box beside the policy (or policies) for which you want to run scripts, then select a script in the drop-down that appears next to the policy name. When you're done associating policies to scripts, click Save.

When a host fails the selected policy, this will trigger the script to run on the host.

If the script fails, you can reset a script automation and trigger the script to run on all targeted hosts again. To do this, deselect the policy in the Policies > Manage automations modal, select Save, and then reselect the policy. This will reset the policy's host passing and failing host counts and retrigger the script automation.

How does it work?

• Online hosts report policy status when on a configurable cadence, with hourly default.
• Fleet will send scripts to the hosts on the first policy failure (first "No" result for the host) or if a policy goes from "Yes" to "No". Policies that remain failed ("No") for a host in consecutive reports will not be resent to the script.

When script automation on a policy is added or switched to a different script, the policy's status will reset for associated hosts. This allows the newly attached script to run on hosts that had previously failed the policy.

• Scripts are run once regardless of exit code.
• When used in policy automation, Fleet does not run shell scripts on Windows hosts or PowerShell scripts on non-Windows hosts.

Via the API

Script policy automation can be managed by setting the script_id field on the Fleet REST API's Add team policy or Edit team policy endpoints.

Via GitOps

To configure script policy automation via GitOps, nest a run_script entry under the policy you want to automate, then make sure you have the same path field both there and in the same team's controls > scripts section. See the GitOps reference documentation for an example.

Conclusion

Fleet now supports running scripts on hosts that fail a policy check. We showed how to set up these automations via the Fleet admin UI, our REST API, and GitOps.

Host condition-related issues can be resolved by running a script on those hosts. You can now automate those resolutions inside Fleet, allowing zero-touch remediation of policy failures on hosts running fleetd.