[API design] Install software and run setup script when Macs boot

articles/automatic-software-install-in-fleet.md

@@ -21,7 +21,7 @@ Fleet allows its users to upload trusted software installation files to be insta
 Current supported software deployment formats:
 - macOS: .pkg
 - Windows: .msi, .exe
-- Linux: .deb
+- Linux: .deb, .rpm
 
 Coming soon:
 - VPP for iOS and iPadOS

articles/deploy-software-packages.md

@@ -46,7 +46,7 @@ To access and manage software in Fleet:
 
 * Click the “Add Software” button in the top right corner, and a dialog will appear.
 
-* Choose a file to upload. `.pkg`, `.msi`, `.exe`, and `.deb` files are supported.
+* Choose a file to upload. `.pkg`, `.msi`, `.exe`, `.rpm`, and `.deb` files are supported.
 
 > Software installer uploads will fail if Fleet is unable to extract information from the installer package such bundle ID and version number.
 

docs/Configuration/yaml-files.md

@@ -84,6 +84,8 @@ policies:
   platform: darwin
   critical: false
   calendar_event_enabled: false
+  run_script:
+    path: "../lib/disable-guest-account.sh"
 - name: Firefox on Linux installed and up to date
   platform: linux
   description: "This policy checks that Firefox is installed and up to date."
@@ -93,7 +95,7 @@ policies:
     package_path: "../lib/linux-firefox.deb.package.yml"
 ```
 
-`default.yml`, `teams/team-name.yml`, or `teams/no-team.yml`
+`default.yml` (for policies that neither install software nor run scripts), `teams/team-name.yml`, or `teams/no-team.yml`
 
 ```yaml
 policies:
@@ -319,7 +321,7 @@ The `software` section allows you to configure packages and Apple App Store apps
 Software for hosts that belong to "No team" have to be defined in `teams/no-team.yml`.
 Software can also be specified in separate files in your `lib/` folder.
 
-- `packages` is a list of software packages (.pkg, .msi, .exe, or .deb) and software specific options.
+- `packages` is a list of software packages (.pkg, .msi, .exe, .rpm, or .deb) and software specific options.
 - `app_store_apps` is a list of Apple App Store apps.
 
 #### Example

docs/Contributing/API-for-contributors.md

@@ -1507,13 +1507,23 @@ NOTE: when updating a policy, team and platform will be ignored.
       "description": "Checks to make sure that the FileVault feature is enabled on macOS devices.",
       "resolution": "Choose Apple menu > System Preferences, then click Security & Privacy. Click the FileVault tab. Click the Lock icon, then enter an administrator name and password. Click Turn On FileVault.",
       "platform": "darwin",
-      "critical": true
-    }
+      "critical": true,
+      "script_id": 123
+    },
+    {
+      "name": "Is Adobe Acrobat installed and up to date?",
+      "query": "SELECT 1 FROM apps WHERE name = 'Adobe Acrobat Reader.app' AND version_compare(bundle_short_version, '23.001.20687') >= 0;",
+      "team": "Workstations",
+      "description": "Checks to make sure that Adobe Acrobat is installed and up to date.",
+      "platform": "darwin",
+      "critical": false,
+      "software_title_id": 12
+    },
   ]
 }
 ```
 
-The field `critical` is available in Fleet Premium.
+The fields `critical`, `script_id`, and `software_title_id` are available in Fleet Premium.
 
 ##### Default response
 
@@ -2771,6 +2781,7 @@ Device-authenticated routes are routes used by the Fleet Desktop application. Un
 - [Migrate device to Fleet from another MDM solution](#migrate-device-to-fleet-from-another-mdm-solution)
 - [Trigger FileVault key escrow](#trigger-filevault-key-escrow)
 - [Report an agent error](#report-an-agent-error)
+- [Register a device with the setup experience](#register-a-device-with-the-setup-experience)
 
 #### Refetch device's host
 
@@ -3174,6 +3185,73 @@ Notifies the server about an agent error, resulting in two outcomes:
 
 `Status: 500`
 
+### Register a device with the setup experience
+
+`POST /api/v1/fleet/device/{token}/setup_experience/start`
+
+##### Parameters
+
+| Name  | Type   | In   | Description                        |
+| ----- | ------ | ---- | ---------------------------------- |
+| token | string | path | The device's authentication token. |
+
+##### Example
+
+`POST /api/v1/fleet/device/8b49859b-1ffa-483d-ad27-85b30aa3c55f/setup_experience/start`
+
+##### Default response
+
+`Status: 201`
+
+### Get the status of a device in the setup experience
+
+`GET /api/v1/fleet/device/{token}/setup_experience/status`
+
+##### Parameters
+
+| Name  | Type   | In   | Description                        |
+| ----- | ------ | ---- | ---------------------------------- |
+| token | string | path | The device's authentication token. |
+
+##### Example
+
+`POST /api/v1/fleet/device/8b49859b-1ffa-483d-ad27-85b30aa3c55f/setup_experience/status`
+
+##### Default response
+
+`Status: 200`
+
+```json
+{
+  "bootstrap_package": {
+    "name": "botstrap_package.pkg",
+    "status": "completed"
+  },
+  "script": {
+    "execution_id": "02e4abba-7d96-4f5b-8c18-ffc5de71bd45",
+    "name": "setup-macos.sh",
+    "status": "pending"
+  },
+  "software": [
+    {
+      "software_title_id": 1,
+      "name": "Google Chrome.app",
+      "status": "installed"
+    },
+    {
+      "software_title_id": 2,
+      "name": "Zoom.us.app",
+      "status": "pending"
+    },
+    {
+      "software_title_id": 3,
+      "name": "Slack.app",
+      "status": "failed"
+    }
+  ]
+}
+```
+
 ---
 
 
@@ -3336,7 +3414,24 @@ If both `team_id` and `team_name` parameters are included, this endpoint will re
 
 ##### Default response
 
-`Status: 204`
+`Status: 200`
+
+```json
+{
+  "scripts": [
+    {
+      "team_id": 3,
+      "id": 6690,
+      "name": "Ensure shields are up"
+    },
+    {
+      "team_id": 3,
+      "id": 10412,
+      "name": "Ensure flux capacitor is charged"
+    }
+  ]
+}
+```
 
 ### Run live script
 

docs/Contributing/research/mdm/software-version-extract.md

@@ -15,6 +15,7 @@
 | `.pkg` | Low        | High     | -                                           |
 | `.exe` | Low        | High     | -                                           |
 | `.deb` | Low        | High     | -                                           |
+| `.rpm` | Low        | High     | -                                           |
 
 More details:
 

docs/Get started/FAQ.md

@@ -80,7 +80,7 @@ Fleet supports the following operating system versions on hosts.
 | Linux   | CentOS 7.1+,  Ubuntu 20.04+, Fedora 38+ |
 | ChromeOS | 112.0.5615.134+                        |
 
-While Fleet may still function partially or fully with OS versions older than those above, Fleet does not actively test against unsupported versions and does not pursue bugs on them. 
+While Fleet may still function partially or fully with OS versions older than those above, Fleet does not actively test against unsupported versions and does not pursue bugs on them.
 
 ## Some notes on compatibility
 
@@ -91,10 +91,12 @@ If a table is not available for your host, Fleet will generally handle things be
 
 ### Linux
 
-Fleet Desktop is supported on Ubuntu and Fedora. 
+Fleet Desktop is supported on Ubuntu and Fedora.
 
 Fedora requires a [gnome extension](https://extensions.gnome.org/extension/615/appindicator-support/) and Google Chrome for Fleet Desktop.
 
+Fleet's default (un)install scripts use `apt-get` for Debian-based distributions, and `dnf` for Red Hat-based distributions. To install packages on CentOS versions prior to 8, either add `dnf` or edit install and uninstall scripts to use the `yum` or `rpm` command.
+
 On Ubuntu, Fleet Desktop currently supports Xorg as X11 server, Wayland is currently not supported. Ubuntu 24.04 comes with Wayland enabled by default. To use X11 instead of Wayland you can set `WaylandEnable=false` in `/etc/gdm3/custom.conf` and reboot.
 
 The `fleetctl package` command is not supported on DISA-STIG distribution.