From b682ee1b079223944280d41b68456baf5c72c8e9 Mon Sep 17 00:00:00 2001 From: Noah Talerman <47070608+noahtalerman@users.noreply.github.com> Date: Tue, 18 Feb 2025 17:31:55 -0500 Subject: [PATCH] Docs v4.64.0 (#26393) Reference doc changes for Fleet 4.64.0 --------- Co-authored-by: Rachael Shaw Co-authored-by: Ian Littman Co-authored-by: Eric --- docs/Configuration/yaml-files.md | 3 + docs/REST API/rest-api.md | 237 ++++++++++++++++++++++++++++++- 2 files changed, 234 insertions(+), 6 deletions(-) diff --git a/docs/Configuration/yaml-files.md b/docs/Configuration/yaml-files.md index 460835798a..006e8cd383 100644 --- a/docs/Configuration/yaml-files.md +++ b/docs/Configuration/yaml-files.md @@ -347,6 +347,9 @@ software: - Customer Support app_store_apps: - app_store_id: '1091189122' + labels_include_any: + - Product + - Marketing ``` Use `labels_include_any` to target hosts that have any label in the array or `labels_exclude_any` to target hosts that don't have any label in the array. Only one of `labels_include_any` or `labels_exclude_any` can be specified. If neither are specified, all hosts are targeted. diff --git a/docs/REST API/rest-api.md b/docs/REST API/rest-api.md index e9c656bd9c..a15d5a0b68 100644 --- a/docs/REST API/rest-api.md +++ b/docs/REST API/rest-api.md @@ -2216,6 +2216,8 @@ the `software` table. | os_settings_disk_encryption | string | query | Filters the hosts by disk encryption status. Valid options are 'verified', 'verifying', 'action_required', 'enforcing', 'failed', or 'removing_enforcement'. **Note: If this filter is used in Fleet Premium without a team ID filter, the results include only hosts that are not assigned to any team.** | | populate_software | string | query | If `false` (or omitted), omits installed software details for each host. If `"without_vulnerability_details"`, include a list of installed software for each host, including which CVEs apply to the installed software versions. `true` adds vulnerability description, CVSS score, and other details when using Fleet Premium. See notes below on performance. | | populate_policies | boolean | query | If `true`, the response will include policy data for each host. | +| populate_users | boolean | query | If `true`, the response will include user data for each host. | +| populate_labels | boolean | query | If `true`, the response will include labels for each host. | > `software_id` is deprecated as of Fleet 4.42. It is maintained for backwards compatibility. Please use the `software_version_id` instead. @@ -2237,7 +2239,7 @@ If `after` is being used with `created_at` or `updated_at`, the table must be sp #### Example -`GET /api/v1/fleet/hosts?page=0&per_page=100&order_key=hostname&query=2ce&populate_software=true&populate_policies=true` +`GET /api/v1/fleet/hosts?page=0&per_page=100&order_key=hostname&query=2ce&populate_software=true&populate_policies=true&populate_users=true&populate_labels=true` ##### Request query parameters @@ -2383,6 +2385,57 @@ If `after` is being used with `created_at` or `updated_at`, the table must be sp "response": "fail", "critical": false } + ], + "users": [ + { + "uid": 0, + "username": "root", + "type": "", + "groupname": "root", + "shell": "/bin/bash" + }, + { + "uid": 1, + "username": "bin", + "type": "", + "groupname": "bin", + "shell": "/sbin/nologin" + } + ], + "labels": [ + { + "created_at": "2021-08-19T02:02:17Z", + "updated_at": "2021-08-19T02:02:17Z", + "id": 6, + "name": "All Hosts", + "description": "All hosts which have enrolled in Fleet", + "query": "SELECT 1;", + "platform": "", + "label_type": "builtin", + "label_membership_type": "dynamic" + }, + { + "created_at": "2021-08-19T02:02:17Z", + "updated_at": "2021-08-19T02:02:17Z", + "id": 9, + "name": "CentOS Linux", + "description": "All CentOS hosts", + "query": "SELECT 1 FROM os_version WHERE platform = 'centos' OR name LIKE '%centos%'", + "platform": "", + "label_type": "builtin", + "label_membership_type": "dynamic" + }, + { + "created_at": "2021-08-19T02:02:17Z", + "updated_at": "2021-08-19T02:02:17Z", + "id": 12, + "name": "All Linux", + "description": "All Linux distributions", + "query": "SELECT 1 FROM osquery_info WHERE build_platform LIKE '%ubuntu%' OR build_distro LIKE '%centos%';", + "platform": "", + "label_type": "builtin", + "label_membership_type": "dynamic" + } ] } ] @@ -3933,6 +3986,7 @@ Resends a configuration profile for the specified host. "name": "Google Chrome.app", "software_package": { "name": "GoogleChrome.pkg", + "platform": "darwin", "version": "125.12.0.3", "self_service": true, "last_install": { @@ -3964,6 +4018,7 @@ Resends a configuration profile for the specified host. "name": "Falcon.app", "software_package": { "name": "FalconSensor-6.44.pkg", + "platform": "darwin", "self_service": false, "last_install": null, "last_uninstall": { @@ -3982,6 +4037,7 @@ Resends a configuration profile for the specified host. "software_package": null, "app_store_app": { "app_store_id": "1091189122", + "platform": "darwin", "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, @@ -4166,8 +4222,14 @@ To lock a macOS host, the host must have MDM turned on. To lock a Windows or Lin ##### Default response -`Status: 204` +`Status: 200` +```json +{ + "device_status": "unlocked", + "pending_action": "lock" +} +``` #### Example @@ -4179,10 +4241,14 @@ To lock a macOS host, the host must have MDM turned on. To lock a Windows or Lin ```json { - "unlock_pin": "123456" + "unlock_pin": "123456", + "device_status": "unlocked", + "pending_action": "lock" } ``` +> To verify the host successfully locked, you can use the [Get host](https://fleetdm.com/docs/rest-api/rest-api#get-host) endpoint to retrieve the host's `mdm.device_status`. + ### Unlock host _Available in Fleet Premium_ @@ -4205,8 +4271,15 @@ To unlock a Windows or Linux host, the host must have [scripts enabled](https:// ##### Default response (Windows or Linux hosts) -`Status: 204` +`Status: 200` +```json +{ + "host_id": 8, + "device_status": "locked", + "pending_action": "unlock" +} +``` ##### Default response (macOS hosts) @@ -4215,10 +4288,14 @@ To unlock a Windows or Linux host, the host must have [scripts enabled](https:// ```json { "host_id": 8, - "unlock_pin": "123456" + "unlock_pin": "123456", + "device_status": "locked", + "pending_action": "unlock" } ``` +> To verify the host successfully unlocked, you can use the [Get host](https://fleetdm.com/docs/rest-api/rest-api#get-host) endpoint to retrieve the host's `mdm.device_status`. macOS hosts require entering `unlock_pin` to unlock. + ### Wipe host Sends a command to wipe the specified macOS, iOS, iPadOS, Windows, or Linux host. The host is wiped once it comes online. @@ -4239,8 +4316,16 @@ To wipe a macOS, iOS, iPadOS, or Windows host, the host must have MDM turned on. ##### Default response -`Status: 204` +`Status: 200` +```json +{ + "device_status": "unlocked", + "pending_action": "wipe" +} +``` + +> To verify the host was successfully wiped, you can use the [Get host](https://fleetdm.com/docs/rest-api/rest-api#get-host) endpoint to retrieve the host's `mdm.device_status`. ### Get host's past activity @@ -5988,6 +6073,7 @@ List software that can or will be automatically installed during macOS setup. If "name": "Firefox.app", "software_package": { "name": "FirefoxInsall.pkg", + "platform": "darwin", "version": "125.6", "self_service": true, "install_during_setup": true @@ -8368,6 +8454,7 @@ This allows you to easily configure scheduled queries that will impact a whole t - [Run script](#run-script) - [Get script result](#get-script-result) - [Add script](#add-script) +- [Modify script](#modify-script) - [Delete script](#delete-script) - [List scripts](#list-scripts) - [Get or download script](#get-or-download-script) @@ -8502,6 +8589,57 @@ echo "hello" } ``` +### Modify script + +Modifies an existing script. + +`PATCH /api/v1/fleet/scripts/:id` + + +#### Parameters + +| Name | Type | In | Description | +| ---- | ------- | ---- | -------------------------------------------- | +| id | integer | path | **Required**. The ID of the script to modify. | +| script | file | form | **Required**. The file containing the script. Filename will be ignored. | + +#### Example + +`PATCH /api/v1/fleet/scripts/1` + + +##### Request headers + +```http +Content-Length: 306 +Content-Type: multipart/form-data; boundary=------------------------f02md47480und42y +``` + +##### Request body + +```http +--------------------------f02md47480und42y +Content-Disposition: form-data; name="script"; filename="myscript.sh" +Content-Type: application/octet-stream +echo "hello" +--------------------------f02md47480und42y-- +``` + +##### Default response + +`Status: 200` + +```json +{ + "id": 1, + "team_id": null, + "name": "script_1.sh", + "created_at": "2023-07-30T13:41:07Z", + "updated_at": "2023-07-30T13:41:07Z" +} +``` + + ### Delete script Deletes an existing script. @@ -8686,6 +8824,7 @@ Deletes the session specified by ID. When the user associated with the session n - [Modify package](#modify-package) - [List App Store apps](#list-app-store-apps) - [Add App Store app](#add-app-store-app) +- [Modify App Store app](#modify-app-store-app) - [List Fleet-maintained apps](#list-fleet-maintained-apps) - [Get Fleet-maintained app](#get-fleet-maintained-app) - [Add Fleet-maintained app](#add-fleet-maintained-app) @@ -8720,6 +8859,8 @@ Get a list of all software. | max_cvss_score | integer | query | _Available in Fleet Premium_. Filters to only include software with vulnerabilities that have a CVSS version 3.x base score lower than what's specified. | | exploit | boolean | query | _Available in Fleet Premium_. If `true`, filters to only include software with vulnerabilities that have been actively exploited in the wild (`cisa_known_exploit: true`). Default is `false`. | | platform | string | query | Filter software titles by platforms. Options are: `"macos"` (alias of `"darwin"`), `"darwin"` `"windows"`, `"linux"`, `"chrome"`, `"ios"`, `"ipados"`. To show titles from multiple platforms, separate the platforms with commas (e.g. `?platform=darwin,windows`). | +| exclude_fleet_maintained_apps | boolean | query | If `true` or `1`, Fleet maintained apps will not be included in the list of `software_titles`. Default is `false` | + #### Example @@ -8738,6 +8879,7 @@ Get a list of all software. "id": 12, "name": "Firefox.app", "software_package": { + "platform": "darwin", "name": "FirefoxInsall.pkg", "version": "125.6", "self_service": true, @@ -9012,6 +9154,7 @@ Returns information about the specified software. By default, `versions` are sor "software_package": { "name": "FalconSensor-6.44.pkg", "version": "6.44", + "platform": "darwin", "installer_id": 23, "team_id": 3, "uploaded_at": "2024-04-01T14:22:58Z", @@ -9087,6 +9230,7 @@ Returns information about the specified software. By default, `versions` are sor "app_store_app": { "name": "Logic Pro", "app_store_id": 1091189122, + "platform": "darwin", "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, @@ -9375,6 +9519,7 @@ Content-Type: application/octet-stream "software_package": { "name": "FalconSensor-6.44.pkg", "version": "6.44", + "platform": "darwin", "installer_id": 23, "team_id": 3, "uploaded_at": "2024-04-01T14:22:58Z", @@ -9459,6 +9604,10 @@ Add App Store (VPP) app purchased in Apple Business Manager. | 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. | +| labels_include_any | array | form | Target hosts that have any label in the array. | +| labels_exclude_any | array | form | Target hosts that don't have any label in the array. | + +Only one of `labels_include_any` or `labels_exclude_any` can be specified. If neither are specified, all hosts are targeted. #### Example @@ -9480,6 +9629,81 @@ Add App Store (VPP) app purchased in Apple Business Manager. `Status: 200` +### Modify 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._ + +Modify App Store (VPP) app's options. + +`PATCH /api/v1/fleet/software/titles/:title_id/app_store_app` + +#### Parameters + +| Name | Type | In | Description | +| ---- | ---- | -- | ----------- | +| team_id | integer | body | **Required**. The team ID. Edits App Store apps from the specified team. | +| self_service | boolean | body | Self-service software is optional and can be installed by the end user. | +| labels_include_any | array | form | Target hosts that have any label in the array. | +| labels_exclude_any | array | form | Target hosts that don't have any label in the array. | + +Only one of `labels_include_any` or `labels_exclude_any` can be specified. If neither are specified, all hosts are targeted. + +#### Example + +`PATCH /api/v1/fleet/software/titles/3467/app_store_app` + +##### Request body + +```json +{ + "team_id": 2, + "self_service": true, + "labels_include_any": [ + "Product", + "Marketing" + ] +} +``` + +##### Default response + +`Status: 200` + +```json +{ + "app_store_app": { + "name": "Logic Pro", + "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, + "labels_include_any": [ + { + "name": "Product", + "id": 12 + }, + { + "name": "Marketing", + "id": 17 + } + ], + "automatic_install_policies": [ + { + "id": 345, + "name": "[Install software] Logic Pro", + } + ], + "status": { + "installed": 3, + "pending": 1, + "failed": 2, + } + } +} +``` + + ### List Fleet-maintained apps > **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. @@ -9563,6 +9787,7 @@ Returns information about the specified Fleet-maintained app. "filename": "1Password-8.10.50-aarch64.zip", "version": "8.10.50", "platform": "darwin", + "url": "https://downloads.1password.com/mac/1Password-8.10.50-aarch64.zip", "install_script": "#!/bin/sh\ninstaller -pkg \"$INSTALLER_PATH\" -target /", "uninstall_script": "#!/bin/sh\npkg_ids=$PACKAGE_ID\nfor pkg_id in '${pkg_ids[@]}'...", }