From 23e80f2ce4f258e7c0f0134a96bb835893beb0ff Mon Sep 17 00:00:00 2001 From: Noah Talerman <47070608+noahtalerman@users.noreply.github.com> Date: Thu, 23 May 2024 17:07:07 -0400 Subject: [PATCH] API design: Deploy security agents to macOS, Windows, and Linux hosts (#19245) API changes for: - #14921 --- docs/Contributing/API-for-contributors.md | 114 ++++++++- docs/REST API/rest-api.md | 278 ++++++++++++++++++++++ 2 files changed, 388 insertions(+), 4 deletions(-) diff --git a/docs/Contributing/API-for-contributors.md b/docs/Contributing/API-for-contributors.md index c89046fefd..08a5018095 100644 --- a/docs/Contributing/API-for-contributors.md +++ b/docs/Contributing/API-for-contributors.md @@ -9,6 +9,7 @@ - [Downloadable installers](#downloadable-installers) - [Setup](#setup) - [Scripts](#scripts) +- [Software](#software) This document includes the internal Fleet API routes that are helpful when developing or contributing to Fleet. @@ -1285,6 +1286,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. | | 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. | @@ -1361,6 +1363,13 @@ If the `name` is not already associated with an existing team, this API route cr } }, "scripts": ["path/to/script.sh"], + "software": [ + { + "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", + } + ] } ] } @@ -2283,6 +2292,8 @@ Device-authenticated routes are routes used by the Fleet Desktop application. Un - [Refetch device's host](#refetch-devices-host) - [Get device's Google Chrome profiles](#get-devices-google-chrome-profiles) - [Get device's mobile device management (MDM) and Munki information](#get-devices-mobile-device-management-mdm-and-munki-information) +- [Get Fleet Desktop information](#get-fleet-desktop-information) +- [Get device's software](#get-devices-software) - [Get device's policies](#get-devices-policies) - [Get device's API features](#get-devices-api-features) - [Get device's transparency URL](#get-devices-transparency-url) @@ -2398,6 +2409,77 @@ In regards to the `notifications` key: - `enforce_bitlocker_encryption` applies only to Windows devices and means that it should encrypt the disk and report the encryption key back to Fleet. +#### Get device's software + +Lists the software installed on the current device. + +`GET /api/v1/fleet/device/{token}/software` + +##### Parameters + +| Name | Type | In | Description | +| ----- | ------ | ---- | ---------------------------------- | +| token | string | path | The device's authentication token. | +| 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.| + +##### Example + +`GET /api/v1/fleet/device/bbb7cdcc-f1d9-4b39-af9e-daa0f35728e8/software` + +##### Default response + +`Status: 200` + +```json +{ + "count": 2, + "software": [ + { + "id": 121, + "name": "Google Chrome.app", + "source": "apps", + "bundle_identifier": "com.google.Chrome", + "status": "failed", + "last_install": { + "install_uuid": "8bbb8ac2-b254-4387-8cba-4d8a0407368b", + "installed_at": "2024-05-15T15:23:57Z" + }, + "installed_versions": [ + { + "version": "121.0", + "last_opened_at": "2024-04-01T23:03:07Z", + "vulnerabilities": ["CVE-2023-1234","CVE-2023-4321","CVE-2023-7654"], + "installed_paths": ["/Applications/Google Chrome.app"] + } + ] + }, + { + "id": 143, + "name": "Firefox.app", + "source": "apps", + "bundle_identifier": "com.google.Chrome", + "status": null, + "last_install": null, + "installed_versions": [ + { + "version": "125.6", + "last_opened_at": "2024-04-01T23:03:07Z", + "vulnerabilities": ["CVE-2023-1234","CVE-2023-4321","CVE-2023-7654"], + "installed_paths": ["/Applications/Firefox.app"] + } + ] + } + ], + "meta": { + "has_next_results": false, + "has_previous_results": false + } +} +``` + + #### Get device's policies _Available in Fleet Premium_ @@ -2758,11 +2840,35 @@ If both `team_id` and `team_name` parameters are included, this endpoint will re #### Example -`POST /api/v1/fleet/mdm/scripts/batch` +`POST /api/v1/fleet/scripts/batch` ##### Default response -`204` +`Status: 204` - - +## Software + +### 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`. | +| 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`. | +| dry_run | bool | query | If `true`, will validate the provided software packages and return any validation errors, but will not apply the changes. | +| 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. | + +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` diff --git a/docs/REST API/rest-api.md b/docs/REST API/rest-api.md index 2da2d82fed..dbb2f72381 100644 --- a/docs/REST API/rest-api.md +++ b/docs/REST API/rest-api.md @@ -1863,6 +1863,8 @@ None. - [List host OS versions](#list-host-os-versions) - [Get host OS version](#get-host-os-version) - [Get host's scripts](#get-hosts-scripts) +- [Get host's software](#get-hosts-software) +- [Install software](#install-software) - [Get hosts report in CSV](#get-hosts-report-in-csv) - [Get host's disk encryption key](#get-hosts-disk-encryption-key) - [Lock host](#lock-host) @@ -1920,6 +1922,7 @@ the `software` table. | policy_response | string | query | **Requires `policy_id`**. Valid options are 'passing' or 'failing'. | | software_version_id | integer | query | The ID of the software version to filter hosts by. | | software_title_id | integer | query | The ID of the software title to filter hosts by. | +| software_status | string | query | The status of the software install to filter hosts by. | | os_version_id | integer | query | The ID of the operating system version to filter hosts by. | | os_name | string | query | The name of the operating system to filter hosts by. `os_version` must also be specified with `os_name` | | os_version | string | query | The version of the operating system to filter hosts by. `os_name` must also be specified with `os_version` | @@ -3752,6 +3755,113 @@ OS vulnerability data is currently available for Windows and macOS. For other pl ``` +### Get host's software + +`GET /api/v1/fleet/hosts/:id/software` + +#### Parameters + +| Name | Type | In | Description | +| ---- | ------- | ---- | ---------------------------- | +| id | integer | path | **Required**. The host's ID. | +| 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.| + +#### Example + +`GET /api/v1/fleet/hosts/123/software` + +##### Default response + +`Status: 200` + +```json +{ + "count": 3, + "software": [ + { + "id": 121, + "name": "Google Chrome.app", + "package_available_for_install": "GoogleChrome.pkg", + "source": "apps", + "status": "failed", + "last_install": { + "install_uuid": "8bbb8ac2-b254-4387-8cba-4d8a0407368b", + "installed_at": "2024-05-15T15:23:57Z" + }, + "installed_versions": [ + { + "version": "121.0", + "last_opened_at": "2024-04-01T23:03:07Z", + "vulnerabilities": ["CVE-2023-1234","CVE-2023-4321","CVE-2023-7654"], + "installed_paths": ["/Applications/Google Chrome.app"] + } + ] + }, + { + "id": 134, + "name": "Falcon.app", + "package_available_for_install": "FalconSensor-6.44.pkg", + "source": "", + "status": null, + "last_install": null, + "installed_versions": [], + }, + { + "id": 147, + "name": "Firefox.app", + "package_available_for_install": null, + "source": "apps", + "bundle_identifier": "org.mozilla.firefox", + "status": null, + "last_install": null, + "installed_versions": [ + { + "version": "118.0", + "last_opened_at": "2024-04-01T23:03:07Z", + "vulnerabilities": ["CVE-2023-1234"], + "installed_paths": ["/Applications/Firefox.app"] + }, + { + "version": "119.0", + "last_opened_at": "2024-04-01T23:03:07Z", + "vulnerabilities": ["CVE-2023-4321","CVE-2023-7654"], + "installed_paths": ["/Downloads/Firefox.app"] + } + ] + }, + ], + "meta": { + "has_next_results": false, + "has_previous_results": false + } +} +``` + +### Install software + +_Available in Fleet Premium._ + +Install software on a macOS, Windows, or Linux (Ubuntu) host. Software title must have `software_package` added to be installed. + +`POST /api/v1/fleet/hosts/:id/software/install/:software_title_id` + +#### Parameters + +| Name | Type | In | Description | +| --------- | ---------- | ---- | -------------------------------------------- | +| id | integer | path | **Required**. The host's ID. | +| software_title_id | integer | path | **Required**. The software title's ID. | + +#### Example + +`POST /api/v1/fleet/hosts/123/software/install/3435` + +##### Default response + +`Status: 202` + ### Get hosts report in CSV Returns the list of hosts corresponding to the search criteria in CSV format, ready for download when @@ -7885,11 +7995,162 @@ Deletes the session specified by ID. When the user associated with the session n ## Software +- [Add software](#add-software) +- [Download software](#download-software) +- [Delete software](#delete-software) +- [Get installation result](#get-installation-result) - [List software](#list-software) - [List software versions](#list-software-versions) - [Get software](#get-software) - [Get software version](#get-software-version) +### Add software + +_Available in Fleet Premium._ + +Add a software package to install on macOS, Windows, and Linux (Ubuntu) hosts. + + +`POST /api/v1/fleet/software/package` + +#### Parameters + +| Name | Type | In | Description | +| ---- | ------- | ---- | -------------------------------------------- | +| 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. | +| 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. | + +#### Example + +`POST /api/v1/fleet/software/package` + +##### Request header + +```http +Content-Length: 8500 +Content-Type: multipart/form-data; boundary=------------------------d8c247122f594ba0 +``` + +##### Request body + +```http +--------------------------d8c247122f594ba0 +Content-Disposition: form-data; name="team_id" +1 +--------------------------d8c247122f594ba0 +Content-Disposition: form-data; name="install_script" +sudo installer -pkg /temp/FalconSensor-6.44.pkg -target / +--------------------------d8c247122f594ba0 +Content-Disposition: form-data; name="pre_install_query" +SELECT 1 FROM macos_profiles WHERE uuid='c9f4f0d5-8426-4eb8-b61b-27c543c9d3db'; +--------------------------d8c247122f594ba0 +Content-Disposition: form-data; name="post_install_script" +sudo /Applications/Falcon.app/Contents/Resources/falconctl license 0123456789ABCDEFGHIJKLMNOPQRSTUV-WX +--------------------------d8c247122f594ba0 +Content-Disposition: form-data; name="software"; filename="FalconSensor-6.44.pkg" +Content-Type: application/octet-stream + +--------------------------d8c247122f594ba0 +``` + +##### Default response + +`Status: 200` + + +### Download software + +_Available in Fleet Premium._ + +Download a software package. + +`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 | form | **Required**. The team ID. Downloads a software package added to the specified team. | +| alt | integer | path | **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: +``` + +### Delete software + +_Available in Fleet Premium._ + +Delete a software package. + +`DELETE /api/v1/fleet/software/titles/:software_title_id/package` + +#### Parameters + +| Name | Type | In | Description | +| ---- | ------- | ---- | -------------------------------------------- | +| 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 + +`DELETE /api/v1/fleet/software/titles/24/package?team_id=2` + +##### Default response + +`Status: 204` + +### Get installation results + +_Available in Fleet Premium._ + +`GET /api/v1/fleet/software/install/results/:install_uuid` + +Get the results of a software installation. + +| Name | Type | In | Description | +| ---- | ------- | ---- | -------------------------------------------- | +| install_uuid | string | path | **Required**. The installation UUID of the software.| + +#### Example + +`GET /api/v1/fleet/software/install/results/b15ce221-e22e-4c6a-afe7-5b3400a017da` + +##### Default response + +`Status: 200` + +```json + { + "install_uuid": "b15ce221-e22e-4c6a-afe7-5b3400a017da", + "software_title": "Falcon.app", + "software_title_id": 8353, + "software_package": "FalconSensor-6.44.pkg", + "host_id": 123, + "host_display_name": "Marko's MacBook Pro", + "status": "failed", + "output": "Installing software...\nError: The operation can’t be completed because the item “Falcon” is in use.", + "pre_install_query_output": "Query returned result\nSuccess", + "post_install_script_output": "Running script...\nExit code: 1 (Failed)\nRolling back software install...\nSuccess" + } +``` + ### List software Get a list of all software. @@ -7907,6 +8168,7 @@ Get a list of all software. | query | string | query | Search query keywords. Searchable fields include `title` and `cve`. | | 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_insall | bool | query | If `true` or `1`, only list software that is available for install (added by the user). Default is `false`. | #### Example @@ -7924,6 +8186,7 @@ Get a list of all software. { "id": 12, "name": "Firefox.app", + "software_package": "FirefoxInstall.pkg", "versions_count": 3, "source": "apps", "browser": "", @@ -7949,6 +8212,7 @@ Get a list of all software. { "id": 22, "name": "Google Chrome.app", + "software_package": null, "versions_count": 5, "source": "apps", "browser": "", @@ -7979,6 +8243,7 @@ Get a list of all software. { "id": 32, "name": "1Password – Password Manager", + "software_package": null, "versions_count": 1, "source": "chrome_extensions", "browser": "chrome", @@ -8099,6 +8364,19 @@ Returns information about the specified software. By default, `versions` are sor "software_title": { "id": 12, "name": "Firefox.app", + "software_package": { + "name": "FalconSensor-6.44.pkg", + "version": "6.44", + "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", + "status": { + "installed": 3, + "pending": 1, + "failed": 2, + } + }, "source": "apps", "browser": "", "hosts_count": 48,