diff --git a/articles/automations.md b/articles/automations.md index e8b2792ca37..adcd954dbba 100644 --- a/articles/automations.md +++ b/articles/automations.md @@ -2,7 +2,8 @@ Fleet supports triggering automations across [activities](#activity-automations), [policies](#policy-automations), [reports](#report-automations), [vulnerabilities](#vulnerability-automations), and [host status](#host-status-automations). -You can configure Fleet to automatically [install software](https://fleetdm.com/guides/automatic-software-install-in-fleet), [run scripts](https://fleetdm.com/guides/policy-automation-run-script), trigger or send report results to webhooks, create tickets, and reserve time in your end users' calendars ([maintenance windows](https://fleetdm.com/announcements/fleet-in-your-calendar-introducing-maintenance-windows)). +You can configure Fleet to automatically [install software](https://fleetdm.com/guides/automatic-software-install-in-fleet), [run scripts](https://fleetdm.com/guides/policy-automation-run-script), [resend configuration profiles](https://fleetdm.com/guides/policy-automation-resend-configuration-profile), trigger or send report results to webhooks, create tickets, and reserve time in your end users' calendars ([maintenance windows](https://fleetdm.com/announcements/fleet-in-your-calendar-introducing-maintenance-windows)). + ## Activity automations @@ -27,11 +28,11 @@ windows), trigger or send report results to webhooks, or create tickets. To learn how to use Fleet's maintenance windows, head to this [article](https://fleetdm.com/announcements/fleet-in-your-calendar-introducing-maintenance-windows). -### Software and scripts +### Software, scripts, and configuration profiles _Available in Fleet Premium_, fleet-level policies only. -By default, software and script automations are only triggered when a policy is newly failing on a host. A policy is "newly failing" if a host updated its response from no response to "fail" or from "pass" to "fail." A policy that remains failing ("fail" → "fail") does not re-trigger the automation. +By default, software, script, and configuration profile automations are only triggered when a policy is newly failing on a host. A policy is "newly failing" if a host updated its response from no response to "fail" or from "pass" to "fail." A policy that remains failing ("fail" → "fail") does not re-trigger the automation. To install software and script automations on every subsequent failing result, instead of only on newly failing hosts, set `continuous_automations_enabled` to `true` on the policy. When enabled, Fleet triggers the software install or script each time it receives a failing response, including consecutive failures ("fail" → "fail"). Because this can retry an automation that doesn't resolve the policy, it may cause a retry loop. Continuous automations don't affect webhooks, tickets, calendar events, or conditional access, which always trigger only on newly failing hosts. diff --git a/articles/policy-automation-resend-configuration-profile.md b/articles/policy-automation-resend-configuration-profile.md new file mode 100644 index 00000000000..3685ca71e0f --- /dev/null +++ b/articles/policy-automation-resend-configuration-profile.md @@ -0,0 +1,54 @@ +# Automatically resend configuration profiles + +Fleet can automatically resend a configuration profile to a host when it fails a policy check. This is useful for re-enforcing settings like certificate renewal, Wi-Fi configuration, Santa daemon health, or CIS Benchmark compliance. + +## Prerequisites + +- MDM turned on for the fleet and hosts enrolled. +- The configuration profile must already be added to the fleet's **Controls** > **OS settings** > **Configuration profiles** > **Profiles** and assigned to the host. + +## Step-by-step instructions + +1. **Add a configuration profile**: Navigate to **Controls** > **OS settings** > **Configuration profiles** > **Profiles**, select the fleet, and add the configuration profile you want to resend. Learn how in the [custom OS settings guide](https://fleetdm.com/guides/custom-os-settings). + +2. **Add a policy**: Navigate to **Policies**, select the fleet, and click **Add policy**. Write a policy query that fails when the configuration needs to be re-enforced and click **Save**. For example, a policy that checks if FileVault is enabled: + +```sql +SELECT 1 FROM disk_encryption WHERE encrypted = 1; +``` + +3. **Set the automation**: In the **Save policy** modal, click **Add automations**, then click the checkbox next to **Resend configuration profile**. From the dropdown, select the profile you want to resend. Click **Save**. + +When a host fails the selected policy, Fleet will resend the configuration profile to the host. + +If you need to retrigger the automation on hosts that had previously failed, deselect the policy in the **Policies > Manage automations** modal, click Save, and then reselect the policy. This will reset the policy's host passing and failing host counts and retrigger the resend. + +## How does it work? +- Online hosts report policy status on a configurable cadence, with hourly default. +- Fleet will resend the configuration profile on the first policy failure or if a policy goes from "Pass" to "Fail". By default, policies that remain failing for a host in consecutive reports will not trigger a resend. +- To resend the profile on every failing result, including consecutive failures, set `continuous_automations_enabled` to `true` on the policy (_Available in Fleet Premium_). Because this can retry a resend that doesn't resolve the policy, it may cause a retry loop. +- If the profile is already pending or verifying delivery, Fleet will skip the resend to avoid interrupting an in-flight delivery. +- If the profile is not assigned to the host, Fleet will skip the resend (no error is raised). + +> When the configuration profile automation on a policy is added or changed, the policy's status will reset for associated hosts. This allows the resend to trigger on hosts that had previously failed the policy. + +## Via the API +Configuration profile policy automation can be managed by setting the `profile_uuid` field on the Fleet REST API's [Add team policy](https://fleetdm.com/docs/rest-api/rest-api#add-team-policy) or [Edit team policy](https://fleetdm.com/docs/rest-api/rest-api#edit-team-policy) endpoints. + +## Via GitOps +To configure configuration profile policy automation via GitOps, nest a `resend_configuration_profile` entry under the policy you want to automate, using the `name` of a profile defined in the same fleet's `controls` section. See the GitOps reference documentation for an example. + +```yaml +policies: + - name: "macOS - FileVault enabled" + query: "SELECT 1 FROM disk_encryption WHERE encrypted = 1;" + platform: darwin + resend_configuration_profile: + name: "Passcode requirements" +``` + + + + + +