API design: Software self-service

docs/Contributing/API-for-contributors.md

@@ -1381,7 +1381,7 @@ If the `name` is not already associated with an existing team, this API route cr
 | mdm.windows_settings                        | object | body  | The Windows-specific MDM settings.                                                                                                                                                                                                    |
 | mdm.windows_settings.custom_settings        | list   | body  | The list of objects consists of a `path` to XML files and `labels` list of label names.                                                                                                                                                         |
 | scripts                                   | list   | body  | A list of script files to add to this team so they can be executed at a later time.                                                                                                                                                 |
-| software                                   | list   | body  | An array of software objects. Each object consists of:`url`- URL to the software package (PKG, MSI, EXE or DEB),`install_script` - command that Fleet runs to install software, `pre_install_query` - condition query that determines if the install will proceed, and `post_install_script` - script that runs after software install.   |
+| software                                   | list   | body  | An array of software objects. Each object consists of:`url`- URL to the software package (PKG, MSI, EXE or DEB),`install_script` - command that Fleet runs to install software, `pre_install_query` - condition query that determines if the install will proceed, `post_install_script` - script that runs after software install, and `self_service` boolean.   |
 | mdm.macos_settings.enable_disk_encryption | bool   | body  | Whether disk encryption should be enabled for hosts that belong to this team.                                                                                                                                                       |
 | force                                     | bool   | query | Force apply the spec even if there are (ignorable) validation errors. Those are unknown keys and agent options-related validations.                                                                                                 |
 | dry_run                                   | bool   | query | Validate the provided JSON for unknown keys and invalid value types and return any validation errors, but do not apply the changes.                                                                                                 |
@@ -1463,6 +1463,7 @@ If the `name` is not already associated with an existing team, this API route cr
           "url": "https://cdn.zoom.us/prod/5.16.10.26186/x64/ZoomInstallerFull.msi",
           "pre_install_query": "SELECT 1 FROM macos_profiles WHERE uuid='c9f4f0d5-8426-4eb8-b61b-27c543c9d3db';",
           "post_install_script": "sudo /Applications/Falcon.app/Contents/Resources/falconctl license 0123456789ABCDEFGHIJKLMNOPQRSTUV-WX",
+          "self_service": true
         }
       ]
     }
@@ -2515,6 +2516,7 @@ Lists the software installed on the current device.
 | Name  | Type   | In   | Description                        |
 | ----- | ------ | ---- | ---------------------------------- |
 | token | string | path | The device's authentication token. |
+| self_service | bool | query | Filter `self_service` software. |
 | query   | string | query | Search query keywords. Searchable fields include `name`. |
 | page | integer | query | Page number of the results to fetch.|
 | per_page | integer | query | Results per page.|
@@ -2535,7 +2537,6 @@ Lists the software installed on the current device.
       "id": 121,
       "name": "Google Chrome.app",
       "source": "apps",
-      "bundle_identifier": "com.google.Chrome",
       "status": "failed",
       "last_install": {
         "install_uuid": "8bbb8ac2-b254-4387-8cba-4d8a0407368b",
@@ -2554,7 +2555,6 @@ Lists the software installed on the current device.
       "id": 143,
       "name": "Firefox.app",
       "source": "apps",
-      "bundle_identifier": "com.google.Chrome",
       "status": null,
       "last_install": null,
       "installed_versions": [
@@ -2574,6 +2574,26 @@ Lists the software installed on the current device.
 }
 ```
 
+#### Install self-service software
+
+Install self-service software on macOS, Windows, or Linux (Ubuntu) host. The software must have a `self_service` flag `true` to be installed.
+
+`POST /api/v1/fleet/device/{token}/software/install/:software_title_id`
+
+##### Parameters
+
+| Name  | Type   | In   | Description                        |
+| ----- | ------ | ---- | ---------------------------------- |
+| token | string | path | **Required**. The device's authentication token. |
+| software_title_id | string | path | **Required**. The software title's ID. |
+
+##### Example
+
+`POST /api/v1/fleet/device/22aada07-dc73-41f2-8452-c0987543fd29/software/install/123`
+
+##### Default response
+
+`Status: 202`
 
 #### Get device's policies
 

docs/REST API/rest-api.md

@@ -4300,6 +4300,7 @@ OS vulnerability data is currently available for Windows and macOS. For other pl
       "id": 121,
       "name": "Google Chrome.app",
       "package_available_for_install": "GoogleChrome.pkg",
+      "self_service": true,
       "source": "apps",
       "status": "failed",
       "last_install": {
@@ -4319,6 +4320,7 @@ OS vulnerability data is currently available for Windows and macOS. For other pl
       "id": 134,
       "name": "Falcon.app",
       "package_available_for_install": "FalconSensor-6.44.pkg",
+      "self_service": false,
       "source": "",
       "status": null,
       "last_install": null,
@@ -4327,7 +4329,6 @@ OS vulnerability data is currently available for Windows and macOS. For other pl
     {
       "id": 147,
       "name": "Firefox.app",
-      "package_available_for_install": null,
       "source": "apps",
       "bundle_identifier": "org.mozilla.firefox",
       "status": null,
@@ -8571,9 +8572,10 @@ Add a software package to install on macOS, Windows, and Linux (Ubuntu) hosts.
 | ----            | ------- | ---- | --------------------------------------------     |
 | software        | file    | form | **Required**. Installer package file. Supported packages are PKG, MSI, EXE, and DEB.   |
 | team_id         | integer | form | **Required**. The team ID. Adds a software package to the specified team. |
-| install_script  | string | form | Command that Fleet runs to install software. If not specified Fleet runs [default install command](#TODO-link-to-docs) for each package type. |
+| install_script  | string | form | Command that Fleet runs to install software. If not specified Fleet runs [default install command](https://github.com/fleetdm/fleet/tree/f71a1f183cc6736205510580c8366153ea083a8d/pkg/file/scripts) for each package type. |
 | pre_install_query  | string | form | Query that is pre-install condition. If the query doesn't return any result, Fleet won't proceed to install. |
 | post_install_script | string | form | The contents of the script to run after install. If the specified script fails (exit code non-zero) software install will be marked as failed and rolled back. |
+| self_service | boolean | form | Self-service software is optional and can be installed by the end user. |
 
 #### Example
 
@@ -8593,6 +8595,9 @@ Content-Type: multipart/form-data; boundary=------------------------d8c247122f59
 Content-Disposition: form-data; name="team_id"
 1
 --------------------------d8c247122f594ba0
+Content-Disposition: form-data; name="self_service"
+true
+--------------------------d8c247122f594ba0
 Content-Disposition: form-data; name="install_script"
 sudo installer -pkg /temp/FalconSensor-6.44.pkg -target /
 --------------------------d8c247122f594ba0
@@ -8625,8 +8630,8 @@ Download a software package.
 
 | Name            | Type    | In   | Description                                      |
 | ----            | ------- | ---- | --------------------------------------------     |
-| software_title_id              | integer | path | **Required**. The ID of the software title to download software package.|
-| team_id | integer | form | **Required**. The team ID. Downloads a software package added to the specified team. |
+| software_title_id   | integer | path | **Required**. The ID of the software title to download software package.|
+| team_id | integer | query | **Required**. The team ID. Downloads a software package added to the specified team. |
 | alt             | integer | query | **Required**. If specified and set to "media", downloads the specified software package. |
 
 #### Example
@@ -8657,7 +8662,7 @@ Delete a software package.
 
 | Name            | Type    | In   | Description                                      |
 | ----            | ------- | ---- | --------------------------------------------     |
-| software_title_id              | integer | path | **Required**. The ID of the software title for the software package to delete. |
+| software_title_id  | integer | path | **Required**. The ID of the software title for the software package to delete. |
 | team_id | integer | query | **Required**. The team ID. Deletes a software package added to the specified team. |
 
 #### Example
@@ -8678,7 +8683,7 @@ Get the results of a software installation.
 
 | Name            | Type    | In   | Description                                      |
 | ----            | ------- | ---- | --------------------------------------------     |
-| install_uuid | string | path | **Required**. The installation UUID of the software.|
+| install_uuid | string | path | **Required**. The software installation UUID.|
 
 #### Example
 
@@ -8721,10 +8726,11 @@ Get a list of all software.
 | team_id                 | integer | query | _Available in Fleet Premium_. Filters the software to only include the software installed on the hosts that are assigned to the specified team.                            |
 | vulnerable              | bool    | query | If true or 1, only list software that has detected vulnerabilities. Default is `false`.                                                                                    |
 | available_for_install   | bool    | query | If `true` or `1`, only list software that is available for install (added by the user). Default is `false`.                                                                |
+| self_service    | bool    | query | If `true` or `1`, only lists self-service software. Default is `false`.  |
 
 #### Example
 
-`GET /api/v1/fleet/software/titles`
+`GET /api/v1/fleet/software/titles?team_id=3`
 
 ##### Default response
 
@@ -8739,6 +8745,7 @@ Get a list of all software.
       "id": 12,
       "name": "Firefox.app",
       "software_package": "FirefoxInstall.pkg",
+      "self_service": true,
       "versions_count": 3,
       "source": "apps",
       "browser": "",
@@ -8765,6 +8772,7 @@ Get a list of all software.
       "id": 22,
       "name": "Google Chrome.app",
       "software_package": null,
+      "self_service": false,
       "versions_count": 5,
       "source": "apps",
       "browser": "",
@@ -8796,6 +8804,7 @@ Get a list of all software.
       "id": 32,
       "name": "1Password – Password Manager",
       "software_package": null,
+      "self_service": false,
       "versions_count": 1,
       "source": "chrome_extensions",
       "browser": "chrome",
@@ -8919,10 +8928,13 @@ Returns information about the specified software. By default, `versions` are sor
     "software_package": {
       "name": "FalconSensor-6.44.pkg",
       "version": "6.44",
+      "installer_id": 23,
+      "team_id": 3,
       "uploaded_at": "2024-04-01T14:22:58Z",
       "install_script": "sudo installer -pkg /temp/FalconSensor-6.44.pkg -target /",
       "pre_install_query": "SELECT 1 FROM macos_profiles WHERE uuid='c9f4f0d5-8426-4eb8-b61b-27c543c9d3db';",
       "post_install_script": "sudo /Applications/Falcon.app/Contents/Resources/falconctl license 0123456789ABCDEFGHIJKLMNOPQRSTUV-WX",
+      "self_service": true,
       "status": {
         "installed": 3,
         "pending": 1,