Docs v4.64.0 (#26393)
Reference doc changes for Fleet 4.64.0 --------- Co-authored-by: Rachael Shaw <r@rachael.wtf> Co-authored-by: Ian Littman <iansltx@gmail.com> Co-authored-by: Eric <eashaw@sailsjs.com>
This commit is contained in:
Noah Talerman
co-authored by
Rachael Shaw
Ian Littman
Eric
Rachael Shaw
Ian Littman
Eric
parent
9dc3ce850b
commit
b682ee1b07
+231
-6
@@ -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[@]}'...",
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user