API design: Policy automations: install software (#22315)

API design for: #19551
fleetdm · Sep 23, 2024 · bda6921 · bda6921
1 parent 11dc2d7
commit bda6921
Show file tree

Hide file tree

Showing 2 changed files with 55 additions and 3 deletions.
diff --git a/docs/Contributing/API-for-contributors.md b/docs/Contributing/API-for-contributors.md
@@ -1219,12 +1219,14 @@ NOTE: when updating a policy, team and platform will be ignored.
       "name": "new policy",
       "description": "This will be a new policy because a policy with the name 'new policy' doesn't exist in Fleet.",
       "query": "SELECT * FROM osquery_info",
+      "team": "No team",
       "resolution": "some resolution steps here",
       "critical": false
     },
     {
       "name": "Is FileVault enabled on macOS devices?",
       "query": "SELECT 1 FROM disk_encryption WHERE user_uuid IS NOT “” AND filevault_status = ‘on’ LIMIT 1;",
+      "team": "Workstations",
       "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",
@@ -3086,7 +3088,24 @@ If both `team_id` and `team_name` parameters are included, this endpoint will re
 
 ##### Default response
 
-`Status: 204`
+`Status: 200`
+
+```json
+{
+  "packages": [
+    {
+      "team_id": 3,
+      "software_title_id": 6690,
+      "url": "https://dl.tailscale.com/stable/tailscale-setup-1.72.0.exe"
+    },
+    {
+      "team_id": 3,
+      "software_title_id": 10412,
+      "url": "https://ftp.mozilla.org/pub/firefox/releases/129.0.2/win64/en-US/Firefox%20Setup%20129.0.2.msi"
+    }
+  ]
+}
+```
 
  ### Run live script
 

diff --git a/docs/REST API/rest-api.md b/docs/REST API/rest-api.md
@@ -6758,6 +6758,29 @@ Team policies work the same as policies, but at the team level.
       "failing_host_count": 0,
       "host_count_updated_at": "2023-12-20T15:23:57Z",
       "calendar_events_enabled": false
+    },
+    {
+      "id": 3,
+      "name": "macOS - install/update Adobe Acrobat",
+      "query": "SELECT 1 FROM apps WHERE name = \"Adobe Acrobat.app\" AND bundle_short_version != \"24.002.21005\";",
+      "description": "Checks if the hard disk is encrypted on Windows devices",
+      "critical": false,
+      "author_id": 43,
+      "author_name": "Alice",
+      "author_email": "alice@example.com",
+      "team_id": 1,
+      "resolution": "Resolution steps",
+      "platform": "darwin",
+      "created_at": "2021-12-16T14:37:37Z",
+      "updated_at": "2021-12-16T16:39:00Z",
+      "passing_host_count": 2300,
+      "failing_host_count": 3,
+      "host_count_updated_at": "2023-12-20T15:23:57Z",
+      "calendar_events_enabled": false,
+      "install_software": {
+        "name": "Adobe Acrobat.app",
+        "software_title_id": 1234
+      }
     }
   ],
   "inherited_policies": [
@@ -6939,6 +6962,7 @@ The semantics for creating a team policy are the same as for global policies, se
 | resolution  | string  | body | The resolution steps for the policy. |
 | platform    | string  | body | Comma-separated target platforms, currently supported values are "windows", "linux", "darwin". The default, an empty string means target all platforms. |
 | critical    | boolean | body | _Available in Fleet Premium_. Mark policy as critical/high impact. |
+| software_title_id  | integer | body | _Available in Fleet Premium_. ID of software title to install if the policy fails. |
 
 Either `query` or `query_id` must be provided.
 
@@ -6982,7 +7006,11 @@ Either `query` or `query_id` must be provided.
     "passing_host_count": 0,
     "failing_host_count": 0,
     "host_count_updated_at": null,
-    "calendar_events_enabled": false
+    "calendar_events_enabled": false,
+    "install_software": {
+      "name": "Adobe Acrobat.app",
+      "software_title_id": 1234
+    }
   }
 }
 ```
@@ -7037,6 +7065,7 @@ Either `query` or `query_id` must be provided.
 | platform    | string  | body | Comma-separated target platforms, currently supported values are "windows", "linux", "darwin". The default, an empty string means target all platforms. |
 | critical    | boolean | body | _Available in Fleet Premium_. Mark policy as critical/high impact. |
 | calendar_events_enabled    | boolean | body | _Available in Fleet Premium_. Whether to trigger calendar events when policy is failing. |
+| software_title_id  | integer | body | _Available in Fleet Premium_. ID of software title to install if the policy fails. |
 
 #### Example
 
@@ -7078,7 +7107,11 @@ Either `query` or `query_id` must be provided.
     "passing_host_count": 0,
     "failing_host_count": 0,
     "host_count_updated_at": null,
-    "calendar_events_enabled": true
+    "calendar_events_enabled": true,
+    "install_software": {
+      "name": "Adobe Acrobat.app",
+      "software_title_id": 1234
+    }
   }
 }
 ```