diff --git a/docs/Configuration/yaml-files.md b/docs/Configuration/yaml-files.md index 7599fd259f9a..fae1c212c192 100644 --- a/docs/Configuration/yaml-files.md +++ b/docs/Configuration/yaml-files.md @@ -354,7 +354,9 @@ software: - `app_store_id` is the ID of the Apple App Store app. You can find this at the end of the app's App Store URL. For example, "Bear - Markdown Notes" URL is "https://apps.apple.com/us/app/bear-markdown-notes/id1016366447" and the `app_store_id` is `1016366447`. -> Make sure to include only the ID itself, and not the `id` prefix shown in the URL. The ID must be wrapped in quotes as shown in the example so that it is processed as a string. +> Make sure to include only the ID itself, and not the `id` prefix shown in the URL. The ID must be wrapped in quotes as shown in the example so that it is processed as a string. + +`self_service` only applies to macOS, and is ignored for other platforms. For example, if the app is supported on macOS, iOS, and iPadOS, and `self_service` is set to `true`, it will be self-service on macOS workstations but not iPhones or iPads. ##### Separate file diff --git a/docs/Contributing/API-for-contributors.md b/docs/Contributing/API-for-contributors.md index 074c3338b4c2..7dfadf76e37e 100644 --- a/docs/Contributing/API-for-contributors.md +++ b/docs/Contributing/API-for-contributors.md @@ -541,6 +541,10 @@ The MDM endpoints exist to support the related command-line interface sub-comman - [Renew VPP token](#renew-vpp-token) - [Delete VPP token](#delete-vpp-token) - [Batch-apply MDM custom settings](#batch-apply-mdm-custom-settings) +- [Batch-apply packages](#batch-apply-packages) +- [Batch-apply App Store apps](#batch-apply-app-store-apps) +- [Get token to download package](#get-token-to-download-package) +- [Download package using a token](#download-package-using-a-token) - [Initiate SSO during DEP enrollment](#initiate-sso-during-dep-enrollment) - [Complete SSO during DEP enrollment](#complete-sso-during-dep-enrollment) - [Over the air enrollment](#over-the-air-enrollment) @@ -1744,7 +1748,7 @@ If the `name` is not already associated with an existing team, this API route cr | scripts | list | body | A list of script files to add to this team so they can be executed at a later time. | | software | object | body | The team's software that will be available for install. | | software.packages | list | body | An array of 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. | -| software.app_store_apps | list | body | An array objects. Each object consists of `app_store_id` - ID of the App Store app formatted as a string (in quotes) rather than a number. | +| software.app_store_apps | list | body | An array of objects. Each object consists of `app_store_id` - ID of the App Store app 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. | @@ -1837,6 +1841,7 @@ If the `name` is not already associated with an existing team, this API route cr "app_store_apps": [ { "app_store_id": "12464567", + "self_service": true } ] } @@ -3377,3 +3382,187 @@ Run a live script and get results back (5 minute timeout). Live scripts only run "exit_code": 0 } ``` +## Software + +### Batch-apply software + +_Available in Fleet Premium._ + +`POST /api/v1/fleet/software/batch` + +This endpoint is asynchronous, meaning it will start a background process to download and apply the software and return a `request_uuid` in the JSON response that can be used to query the status of the batch-apply (using the `GET /api/v1/fleet/software/batch/:request_uuid` endpoint defined below). + +#### Parameters + +| Name | Type | In | Description | +| --------- | ------ | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| team_name | string | query | The name of the team to add the software package to. Ommitting these parameters will add software to 'No Team'. | +| dry_run | bool | query | If `true`, will validate the provided software packages and return any validation errors, but will not apply the changes. | +| software | object | body | The team's software that will be available for install. | +| software.packages | list | body | An array of 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 `uninstall_script` - command that Fleet runs to uninstall software. | + +#### Example + +`POST /api/v1/fleet/software/batch` + +##### Default response + +`Status: 200` +```json +{ + "request_uuid": "ec23c7b6-c336-4109-b89d-6afd859659b4", +} +``` + +### Get status of software batch-apply request + +_Available in Fleet Premium._ + +`GET /api/v1/fleet/software/batch/:request_uuid` + +This endpoint allows querying the status of a batch-apply software request (`POST /api/v1/fleet/software/batch`). +Returns `"status"` field that can be one of `"processing"`, `"complete"` or `"failed"`. +If `"status"` is `"completed"` then the `"packages"` field contains the applied packages. +If `"status"` is `"processing"` then the operation is ongoing and the request should be retried. +If `"status"` is `"failed"` then the `"message"` field contains the error message. + +#### Parameters + +| Name | Type | In | Description | +| ------------ | ------ | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| request_uuid | string | query | The request_uuid returned by the `POST /api/v1/fleet/software/batch` endpoint. | +| team_name | string | query | The name of the team to add the software package to. Ommitting these parameters will add software to 'No Team'. | +| dry_run | bool | query | If `true`, will validate the provided software packages and return any validation errors, but will not apply the changes. | + +##### Default responses + +`Status: 200` +```json +{ + "status": "processing", + "message": "", + "packages": null +} +``` + +`Status: 200` +```json +{ + "status": "completed", + "message": "", + "packages": [ + { + "team_id": 1, + "title_id": 2751, + "url": "https://ftp.mozilla.org/pub/firefox/releases/129.0.2/win64/en-US/Firefox%20Setup%20129.0.2.msi" + } + ] +} +``` + +`Status: 200` +```json +{ + "status": "failed", + "message": "validation failed: software.url Couldn't edit software. URL (\"https://foobar.does.not.exist.com\") returned \"Not Found\". Please make sure that URLs are reachable from your Fleet server.", + "packages": null +} +``` + +### Batch-apply App Store apps + +_Available in Fleet Premium._ + +`POST /api/latest/fleet/software/app_store_apps/batch` + +#### Parameters + +| Name | Type | In | Description | +| --------- | ------ | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| team_name | string | query | The name of the team to add the software package to. Ommitting this parameter will add software to "No team". | +| dry_run | bool | query | If `true`, will validate the provided VPP apps and return any validation errors, but will not apply the changes. | +| app_store_apps | list | body | An array of objects. Each object contains `app_store_id` and `self_service`. | +| app_store_apps.app_store_id | string | body | ID of the App Store app. | +| app_store_apps.self_service | boolean | body | Whether the VPP app is "Self-service" or not. | + +#### Example + +`POST /api/latest/fleet/software/app_store_apps/batch` +```json +{ + "team_name": "Foobar", + "app_store_apps": { + { + "app_store_id": "597799333", + "self_service": false, + }, + { + "app_store_id": "497799835", + "self_service": true, + } + } +} +``` + +##### Default response + +`Status: 204` + +### Get token to download package + +_Available in Fleet Premium._ + +`POST /api/v1/fleet/software/titles/:software_title_id/package/token?alt=media` + +The returned token is a one-time use token that expires after 10 minutes. + +#### Parameters + +| Name | Type | In | Description | +|-------------------|---------|-------|------------------------------------------------------------------| +| software_title_id | integer | path | **Required**. The ID of the software title for software package. | +| team_id | integer | query | **Required**. The team ID containing the software package. | +| alt | integer | query | **Required**. Must be specified and set to "media". | + +#### Example + +`POST /api/v1/fleet/software/titles/123/package/token?alt=media&team_id=2` + +##### Default response + +`Status: 200` + +```json +{ + "token": "e905e33e-07fe-4f82-889c-4848ed7eecb7" +} +``` + +### Download package using a token + +_Available in Fleet Premium._ + +`GET /api/v1/fleet/software/titles/:software_title_id/package/token/:token?alt=media` + +#### Parameters + +| Name | Type | In | Description | +|-------------------|---------|------|--------------------------------------------------------------------------| +| software_title_id | integer | path | **Required**. The ID of the software title to download software package. | +| token | string | path | **Required**. The token to download the software package. | + +#### Example + +`GET /api/v1/fleet/software/titles/123/package/token/e905e33e-07fe-4f82-889c-4848ed7eecb7` + +##### Default response + +`Status: 200` + +```http +Status: 200 +Content-Type: application/octet-stream +Content-Disposition: attachment +Content-Length: +Body: +``` diff --git a/docs/REST API/rest-api.md b/docs/REST API/rest-api.md index 0a760c32d5fc..5eefe0ed2653 100644 --- a/docs/REST API/rest-api.md +++ b/docs/REST API/rest-api.md @@ -4295,8 +4295,10 @@ Resends a configuration profile for the specified host. "name": "Logic Pro", "software_package": null "app_store_app": { - "app_store_id": "1091189122" + "app_store_id": "1091189122", + "icon_url": "https://is1-ssl.mzstatic.com/image/thumb/Purple221/v4/f4/25/1f/f4251f60-e27a-6f05-daa7-9f3a63aac929/AppIcon-0-0-85-220-0-0-4-0-0-2x-0-0-0-0-0.png/512x512bb.png" "version": "2.04", + "self_service": false, "last_install": { "command_uuid": "0aa14ae5-58fe-491a-ac9a-e4ee2b3aac40", "installed_at": "2024-05-15T15:23:57Z" @@ -6442,7 +6444,8 @@ None. ] ``` -Get Volume Purchasing Program (VPP) +### Get Volume Purchasing Program (VPP) + > **Experimental feature**. This feature is undergoing rapid improvement, which may result in breaking changes to the API or configuration surface. It is not recommended for use in automated workflows. @@ -8652,10 +8655,6 @@ Deletes the session specified by ID. When the user associated with the session n - [Get package install result](#get-package-install-result) - [Download package](#download-package) - [Delete package or App Store app](#delete-package-or-app-store-app) -- [Batch-apply software](#batch-apply-software) -- [Batch-apply app store apps](#batch-apply-app-store-apps) -- [Get token to download package](#get-token-to-download-package) -- [Download package using a token](#download-package-using-a-token) ### List software @@ -9026,9 +9025,10 @@ Returns information about the specified software. By default, `versions` are sor "software_package": null, "app_store_app": { "name": "Logic Pro", - "app_store_id": "1091189122", + "app_store_id": 1091189122, "latest_version": "2.04", "icon_url": "https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/f1/65/1e/a4844ccd-486d-455f-bb31-67336fe46b14/AppIcon-1x_U007emarketing-0-7-0-85-220-0.png/512x512bb.jpg", + "self_service": true, "status": { "installed": 3, "pending": 1, @@ -9107,6 +9107,7 @@ Returns information about the specified software version. } ``` + ### Get operating system version Retrieves information about the specified operating system (OS) version. @@ -9379,6 +9380,7 @@ Add App Store (VPP) app purchased in Apple Business Manager. | app_store_id | string | body | **Required.** The ID of App Store app. | | team_id | integer | body | **Required**. The team ID. Adds VPP software to the specified team. | | platform | string | body | The platform of the app (`darwin`, `ios`, or `ipados`). Default is `darwin`. | +| self_service | boolean | body | Self-service software is optional and can be installed by the end user. | #### Example @@ -9391,6 +9393,7 @@ Add App Store (VPP) app purchased in Apple Business Manager. "app_store_id": "497799835", "team_id": 2, "platform": "ipados" + "self_service": true } ``` @@ -9398,38 +9401,6 @@ Add App Store (VPP) app purchased in Apple Business Manager. `Status: 200` -### Download package - -> **Experimental feature**. This feature is undergoing rapid improvement, which may result in breaking changes to the API or configuration surface. It is not recommended for use in automated workflows. - -_Available in Fleet Premium._ - -`GET /api/v1/fleet/software/titles/:software_title_id/package?alt=media` - -#### Parameters - -| Name | Type | In | Description | -| ---- | ------- | ---- | -------------------------------------------- | -| 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 - -`GET /api/v1/fleet/software/titles/123/package?alt=media?team_id=2` - -##### Default response - -`Status: 200` - -```http -Status: 200 -Content-Type: application/octet-stream -Content-Disposition: attachment -Content-Length: -Body: -``` - ### Install package or App Store app > **Experimental feature**. This feature is undergoing rapid improvement, which may result in breaking changes to the API or configuration surface. It is not recommended for use in automated workflows. @@ -9487,7 +9458,7 @@ _Available in Fleet Premium._ `GET /api/v1/fleet/software/install/:install_uuid/results` -Get the results of a software package install. +Get the results of a software package install. To get the results of an App Store app install, use the [List MDM commands](#list-mdm-commands) and [Get MDM command results](#get-mdm-command-results) API enpoints. Fleet uses an MDM command to install App Store apps. @@ -9518,141 +9489,62 @@ To get the results of an App Store app install, use the [List MDM commands](#lis } ``` -### Delete package or App Store app +### Download package > **Experimental feature**. This feature is undergoing rapid improvement, which may result in breaking changes to the API or configuration surface. It is not recommended for use in automated workflows. _Available in Fleet Premium._ -Deletes software that's available for install (package or App Store app). - -`DELETE /api/v1/fleet/software/titles/:software_title_id/available_for_install` +`GET /api/v1/fleet/software/titles/:software_title_id/package?alt=media` #### Parameters | Name | Type | In | Description | | ---- | ------- | ---- | -------------------------------------------- | -| software_title_id | integer | path | **Required**. The ID of the software title to delete software available for install. | -| team_id | integer | query | **Required**. The team ID. Deletes a software package added to the specified team. | - -#### Example - -`DELETE /api/v1/fleet/software/titles/24/available_for_install?team_id=2` - -##### Default response - -`Status: 204` - -### Batch-apply software - -_Available in Fleet Premium._ - -`POST /api/v1/fleet/software/batch` - -#### Parameters - -| Name | Type | In | Description | -| --------- | ------ | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| team_id | number | query | The ID of the team to add the software package to. Only one team identifier (`team_id` or `team_name`) can be included in the request; omit this parameter if using `team_name`. Omitting these parameters will add software to "No Team". | -| team_name | string | query | The name of the team to add the software package to. Only one team identifier (`team_id` or `team_name`) can be included in the request; omit this parameter if using `team_id`. Omitting these parameters will add software to "No Team". | -| dry_run | bool | query | If `true`, will validate the provided software packages and return any validation errors, but will not apply the changes. | -| software | object | body | The team's software that will be available for install. | -| software.packages | list | body | An array of 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 `uninstall_script` - command that Fleet runs to uninstall software. | -| software.app_store_apps | list | body | An array objects. Each object consists of `app_store_id` - ID of the App Store app. | - -If both `team_id` and `team_name` parameters are included, this endpoint will respond with an error. If no `team_name` or `team_id` is provided, the scripts will be applied for **all hosts**. - -#### Example - -`POST /api/v1/fleet/software/batch` - -##### Default response - -`Status: 204` - -### Batch-apply app store apps - -_Available in Fleet Premium._ - -`POST /api/v1/fleet/software/app_store_apps/batch` - -#### Parameters - -| Name | Type | In | Description | -|-----------------|---------|-------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| team_name | integer | query | **Required**. The name of the team to add the app to. | -| dry_run | bool | query | If `true`, will validate the provided apps and return any validation errors, but will not apply the changes. | -| apps_store_apps | list | body | The list of objects containing `app_store_id`: a string representation of the app's App ID, `self_service`: a bool indicating if the app's installation can be initiated by end users. | - -> Note that this endpoint replaces all apps associated with a team. - -#### Example - -`POST /api/v1/fleet/software/app_store_apps/batch` - -#### Default response - -`Status: 204` - -### Get token to download package - -_Available in Fleet Premium._ - -`POST /api/v1/fleet/software/titles/:software_title_id/package/token?alt=media` - -The returned token is a one-time use token that expires after 10 minutes. - -#### Parameters - -| Name | Type | In | Description | -|-------------------|---------|-------|------------------------------------------------------------------| -| software_title_id | integer | path | **Required**. The ID of the software title for software package. | -| team_id | integer | query | **Required**. The team ID containing the software package. | -| alt | integer | query | **Required**. Must be specified and set to "media". | +| 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 -`POST /api/v1/fleet/software/titles/123/package/token?alt=media&team_id=2` +`GET /api/v1/fleet/software/titles/123/package?alt=media?team_id=2` ##### Default response `Status: 200` -```json -{ - "token": "e905e33e-07fe-4f82-889c-4848ed7eecb7" -} +```http +Status: 200 +Content-Type: application/octet-stream +Content-Disposition: attachment +Content-Length: +Body: ``` -### Download package using a token +### Delete package or App Store app + +> **Experimental feature**. This feature is undergoing rapid improvement, which may result in breaking changes to the API or configuration surface. It is not recommended for use in automated workflows. _Available in Fleet Premium._ -`GET /api/v1/fleet/software/titles/:software_title_id/package/token/:token?alt=media` +Deletes software that's available for install (package or App Store app). + +`DELETE /api/v1/fleet/software/titles/:software_title_id/available_for_install` #### Parameters -| Name | Type | In | Description | -|-------------------|---------|------|--------------------------------------------------------------------------| -| software_title_id | integer | path | **Required**. The ID of the software title to download software package. | -| token | string | path | **Required**. The token to download the software package. | +| Name | Type | In | Description | +| ---- | ------- | ---- | -------------------------------------------- | +| software_title_id | integer | path | **Required**. The ID of the software title to delete software available for install. | +| team_id | integer | query | **Required**. The team ID. Deletes a software package added to the specified team. | #### Example -`GET /api/v1/fleet/software/titles/123/package/token/e905e33e-07fe-4f82-889c-4848ed7eecb7` +`DELETE /api/v1/fleet/software/titles/24/available_for_install?team_id=2` ##### Default response -`Status: 200` - -```http -Status: 200 -Content-Type: application/octet-stream -Content-Disposition: attachment -Content-Length: -Body: -``` - +`Status: 204` ## Vulnerabilities