diff --git a/docs/Configuration/yaml-files.md b/docs/Configuration/yaml-files.md index f66c79f1e751..7599fd259f9a 100644 --- a/docs/Configuration/yaml-files.md +++ b/docs/Configuration/yaml-files.md @@ -6,14 +6,16 @@ To learn how to set up a GitOps workflow see the [Fleet GitOps repo](https://git ## File structure -- `default.yml`- File where you define the queries, policies, controls, and agent options for all hosts. If you're using Fleet Premium, this file updates queries and policies that run on all hosts ("All teams"). Controls and agent options are defined for hosts on "No team." -- `teams/` - Folder where you define your teams in Fleet. These `teams/team-name.yml` files define the controls, queries, policies, and agent options for hosts assigned to the specified team. Teams are available in Fleet Premium. +- `default.yml` - File where you define the queries, policies and agent options for all hosts. If you're using Fleet Premium, this file updates queries and policies that run on all hosts ("All teams"). +- `teams/no-team.yml` - File where you define the policies, controls, and software for hosts on "No team". Available in Fleet Premium. +- `teams/` - Folder where you define your teams in Fleet. These `teams/team-name.yml` files define the controls, queries, policies, software, and agent options for hosts assigned to the specified team. Available in Fleet Premium. - `lib/` - Folder where you define policies, queries, configuration profiles, scripts, and agent options. These files can be referenced in top level keys in the `default.yml` file and the files in the `teams/` folder. - `.github/workflows/workflow.yml` - The GitHub workflow file where you can add [environment variables](https://docs.github.com/en/actions/learn-github-actions/variables#defining-environment-variables-for-a-single-workflow). -The following files are responsible for running the GitHub action. Most users don't need to edit these files. +The following files are responsible for running the GitHub action or GitLab CI/CD. Most users don't need to edit these files. - `gitops.sh` - The bash script that applies the latest configuration to Fleet. This script is used in the GitHub action file. - `.github/gitops-action/action.yml` - The GitHub action that runs `gitops.sh`. This action is used in the GitHub workflow file. It can also be used in other workflows. +- `.gitlab-ci.yml` - The GitLab CI/CD file that applies the latest configuration to Fleet. ## Configuration options @@ -24,8 +26,7 @@ name: # Only teams/team-name.yml. To edit a team's name, change `name` but don't policies: queries: agent_options: -controls: -software: +controls: # Can be defined in teams/no-team.yml too. org_settings: # Only default.yml team_settings: # Only teams/team-name.yml ``` @@ -40,6 +41,8 @@ team_settings: # Only teams/team-name.yml ### policies Polcies can be specified inline in your `default.yml` file or `teams/team-name.yml` files. They can also be specified in separate files in your `lib/` folder. +Policies defined in `default.yml` run on **all** hosts. +Policies defined in `teams/no-team.yml` run on hosts that belong to "No team". #### Options @@ -81,9 +84,16 @@ policies: platform: darwin critical: false calendar_event_enabled: false +- name: Firefox on Linux installed and up to date + platform: linux + description: "This policy checks that Firefox is installed and up to date." + resolution: "Install Firefox version 129.0.2 or higher." + query: "SELECT 1 FROM deb_packages WHERE name = 'firefox' AND version_compare(version, '129.0.2') >= 0;" + install_software: + package_path: "../lib/linux-firefox.deb.package.yml" ``` -`default.yml` or `teams/team-name.yml` +`default.yml`, `teams/team-name.yml`, or `teams/no-team.yml` ```yaml policies: @@ -210,6 +220,8 @@ queries: The `controls` section allows you to configure scripts and device management (MDM) features in Fleet. +Controls for hosts that are in "No team" can be defined in `default.yml` or in `teams/no-team.yml` (but not in both files). + - `scripts` is a list of paths to macOS, Windows, or Linux scripts. - `windows_enabled_and_configured` specifies whether or not to turn on Windows MDM features (default: `false`). Can only be configured for all teams (`default.yml`). - `enable_disk_encryption` specifies whether or not to enforce disk encryption on macOS and Windows hosts (default: `false`). @@ -304,11 +316,15 @@ Can only be configure for all teams (`default.yml`). > **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. The `software` section allows you to configure packages and Apple App Store apps that you want to install on your hosts. +Software for hosts that belong to "No team" have to be defined in `teams/no-team.yml`. +Software can also be specified in separate files in your `lib/` folder. - `packages` is a list of software packages (.pkg, .msi, .exe, or .deb) and software specific options. - `app_store_apps` is a list of Apple App Store apps. -##### Example +#### Example + +##### Inline ```yaml software: @@ -326,7 +342,7 @@ software: - app_store_id: '1091189122' ``` -#### packages +##### packages - `url` specifies the URL at which the software is located. Fleet will download the software and upload it to S3 (default: `""`). - `install_script.path` specifies the command Fleet will run on hosts to install software. The [default script](https://github.com/fleetdm/fleet/tree/main/pkg/file/scripts) is dependent on the software type (i.e. .pkg). @@ -334,12 +350,41 @@ software: - `post_install_script.path` is the script Fleet will run on hosts after intalling software (default: `""`). - `self_service` specifies whether or not end users can install from **Fleet Desktop > Self-service**. -#### app_store_apps +##### app_store_apps - `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. +##### Separate file + +`lib/software-name.package.yml`: + +```yaml +url: https://dl.tailscale.com/stable/tailscale-setup-1.72.0.exe +install_script: + path: ../lib/software/tailscale-install-script.ps1 +self_service: true +``` + +`lib/software/tailscale-install-script.ps1` + +```yaml +$exeFilePath = "${env:INSTALLER_PATH}" +$installProcess = Start-Process $exeFilePath ` + -ArgumentList "/quiet /norestart" ` + -PassThru -Verb RunAs -Wait +``` + +`default.yml`, `teams/team-name.yml`, or `teams/no-team.yml` + +```yaml +software: + packages: + - path: ../lib/software-name.package.yml +# path is relative to default.yml or teams/team-name.yml +``` + ### org_settings and team_settings #### features @@ -640,6 +685,19 @@ Once the IdP settings are configured, you can use the [`controls.macos_setup.ena Can only be configured for all teams (`org_settings`). +##### end_user_authentication + +The `end_user_authentication` section lets you define the identity provider (IdP) settings used for end user authentication during Automated Device Enrollment (ADE). Learn more about end user authentication in Fleet [here](https://fleetdm.com/guides/macos-setup-experience#end-user-authentication-and-eula). + +Once the IdP settings are configured, you can use the [`controls.macos_setup.enable_end_user_authentication`](#macos_setup) key to control the end user experience during ADE. + +- `idp_name` is the human-friendly name for the identity provider that will provide single sign-on authentication (default: `""`). +- `entity_id` is the entity ID: a Uniform Resource Identifier (URI) that you use to identify Fleet when configuring the identity provider. It must exactly match the Entity ID field used in identity provider configuration (default: `""`). +- `metadata` is the metadata (in XML format) provided by the identity provider. (default: `""`) +- `metadata_url` is the URL that references the identity provider metadata. Only one of `metadata` or `metadata_url` is required (default: `""`). + +Can only be configured for all teams (`org_settings`). + diff --git a/docs/Contributing/API-for-contributors.md b/docs/Contributing/API-for-contributors.md index ec39149199a1..2e8efe70ca49 100644 --- a/docs/Contributing/API-for-contributors.md +++ b/docs/Contributing/API-for-contributors.md @@ -543,11 +543,13 @@ The MDM endpoints exist to support the related command-line interface sub-comman - [Batch-apply MDM custom settings](#batch-apply-mdm-custom-settings) - [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) - [Preassign profiles to devices](#preassign-profiles-to-devices) - [Match preassigned profiles](#match-preassigned-profiles) - [Get FileVault statistics](#get-filevault-statistics) - [Upload VPP content token](#upload-vpp-content-token) - [Disable VPP](#disable-vpp) +- [Get an over the air (OTA) enrollment profile](#get-an-over-the-air-ota-enrollment-profile) ### Generate Apple Business Manager public key (ADE) @@ -1029,6 +1031,34 @@ If the credentials are valid, the server redirects the client to the Fleet UI. T - `profile_token` is a token that can be used to download an enrollment profile (.mobileconfig). - `eula_token` (optional) if an EULA was uploaded, this contains a token that can be used to view the EULA document. +### Over the air enrollment + +This endpoint handles over the air (OTA) MDM enrollments + +`POST /api/v1/fleet/ota_enrollment` + +#### Parameters + +| Name | Type | In | Description | +| ------------------- | ------ | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| enroll_secret | string | url | **Required** Assigns the host to a team with a matching enroll secret | +| XML device response | XML | body | **Required**. The XML response from the device. Fields are documented [here](https://developer.apple.com/library/archive/documentation/NetworkingInternet/Conceptual/iPhoneOTAConfiguration/ConfigurationProfileExamples/ConfigurationProfileExamples.html#//apple_ref/doc/uid/TP40009505-CH4-SW7) | + +> Note: enroll secrets can contain special characters. Ensure any special characters are [properly escaped](https://developer.mozilla.org/en-US/docs/Glossary/Percent-encoding). + +#### Example + +`POST /api/v1/fleet/ota_enrollment?enroll_secret=0Z6IuKpKU4y7xl%2BZcrp2gPcMi1kKNs3p` + +##### Default response + +`Status: 200` + +Per [the spec](https://developer.apple.com/library/archive/documentation/NetworkingInternet/Conceptual/iPhoneOTAConfiguration/Introduction/Introduction.html#//apple_ref/doc/uid/TP40009505-CH1-SW1), the response is different depending on the signature of the XML device response: + +- If the body is signed with a certificate that can be validated by our root SCEP certificate, it returns an enrollment profile. +- Otherwise, it returns a SCEP payload. + ### Preassign profiles to devices _Available in Fleet Premium_ @@ -1453,12 +1483,14 @@ NOTE: when updating a policy, team and platform will be ignored. "name": "new policy", "description": "This will be a new policy because a policy with the name 'new policy' doesn't exist in Fleet.", "query": "SELECT * FROM osquery_info", + "team": "No team", "resolution": "some resolution steps here", "critical": false }, { "name": "Is FileVault enabled on macOS devices?", "query": "SELECT 1 FROM disk_encryption WHERE user_uuid IS NOT “” AND filevault_status = ‘on’ LIMIT 1;", + "team": "Workstations", "description": "Checks to make sure that the FileVault feature is enabled on macOS devices.", "resolution": "Choose Apple menu > System Preferences, then click Security & Privacy. Click the FileVault tab. Click the Lock icon, then enter an administrator name and password. Click Turn On FileVault.", "platform": "darwin", @@ -3320,7 +3352,24 @@ If both `team_id` and `team_name` parameters are included, this endpoint will re ##### Default response -`Status: 204` +`Status: 200` + +```json +{ + "packages": [ + { + "team_id": 3, + "software_title_id": 6690, + "url": "https://dl.tailscale.com/stable/tailscale-setup-1.72.0.exe" + }, + { + "team_id": 3, + "software_title_id": 10412, + "url": "https://ftp.mozilla.org/pub/firefox/releases/129.0.2/win64/en-US/Firefox%20Setup%20129.0.2.msi" + } + ] +} +``` ### Run live script @@ -3420,3 +3469,71 @@ Content-Disposition: attachment Content-Length: Body: ``` + +### Get an over the air (OTA) enrollment profile + +`GET /api/v1/fleet/enrollment_profiles/ota` + +The returned value is a signed `.mobileconfig` OTA profile. + +#### Parameters + +| Name | Type | In | Description | +|-------------------|---------|-------|----------------------------------------------------------------------------------| +| enroll_secret | string | query | **Required**. The enroll secret of the team this host will be assigned to. | + +#### Example + +`GET /api/v1/fleet/enrollment_profiles/ota?enroll_secret=foobar` + +##### Default response + +`Status: 200` + +**Note** To confirm success, it is important for clients to match content length with the response +header (this is done automatically by most clients, including the browser) rather than relying +solely on the response status code returned by this endpoint. + +##### Example response headers + +```http + Content-Length: 542 + Content-Type: application/x-apple-aspen-config; charset=urf-8 + Content-Disposition: attachment;filename="fleet-mdm-enrollment-profile.mobileconfig" + X-Content-Type-Options: nosniff +``` + +###### Example response body + +```xml + + + + + PayloadContent + + URL + https://foo.example.com/api/fleet/ota_enrollment?enroll_secret=foobar + DeviceAttributes + + UDID + VERSION + PRODUCT + SERIAL + + + PayloadOrganization + Acme Inc. + PayloadDisplayName + Acme Inc. enrollment + PayloadVersion + 1 + PayloadUUID + fdb376e5-b5bb-4d8c-829e-e90865f990c9 + PayloadIdentifier + com.fleetdm.fleet.mdm.apple.ota + PayloadType + Profile Service + + +``` diff --git a/docs/REST API/rest-api.md b/docs/REST API/rest-api.md index c160aac679ff..d7b8b8f172da 100644 --- a/docs/REST API/rest-api.md +++ b/docs/REST API/rest-api.md @@ -484,6 +484,22 @@ for pagination. For a comprehensive list of activity types and detailed informat ```json { "activities": [ + { + "created_at": "2023-07-27T14:35:08Z", + "id": 25, + "actor_full_name": "Anna Chao", + "actor_id": 3, + "actor_gravatar": "", + "actor_email": "", + "type": "uninstalled_software", + "details": { + "host_id": 1, + "host_display_name": "Marko's MacBook Pro", + "software_title": "Adobe Acrobat.app", + "script_execution_id": "eeeddb94-52d3-4071-8b18-7322cd382abb", + "status": "failed" + } + }, { "created_at": "2021-07-30T13:41:07Z", "id": 24, @@ -4241,7 +4257,7 @@ Resends a configuration profile for the specified host. "last_install": { "install_uuid": "8bbb8ac2-b254-4387-8cba-4d8a0407368b", "installed_at": "2024-05-15T15:23:57Z" - }, + } }, "app_store_app": null "source": "apps", @@ -4262,10 +4278,16 @@ Resends a configuration profile for the specified host. "name": "FalconSensor-6.44.pkg" "self_service": false, "last_install": null + "last_install": null, + "last_uninstall": { + "script_execution_id": "ed579e73-0f41-46c8-aaf4-3c1e5880ed27", + "uninstalled_at": "2024-05-15T15:23:57Z" + } }, "app_store_app": null "source": "", "status": null, + "status": "pending_uninstall", "installed_versions": [], }, { @@ -4546,6 +4568,38 @@ To wipe a macOS, iOS, iPadOS, or Windows host, the host must have MDM turned on. ```json { "activities": [ + { + "created_at": "2023-07-27T14:35:08Z", + "actor_id": 1, + "actor_full_name": "Anna Chao", + "id": 4, + "actor_gravatar": "", + "actor_email": "", + "type": "uninstalled_software", + "details": { + "host_id": 1, + "host_display_name": "Marko’s MacBook Pro", + "software_title": "Adobe Acrobat.app", + "script_execution_id": "ecf22dba-07dc-40a9-b122-5480e948b756", + "status": "failed" + } + }, + { + "created_at": "2023-07-27T14:35:08Z", + "actor_id": 1, + "actor_full_name": "Anna Chao", + "id": 3, + "actor_gravatar": "", + "actor_email": "", + "type": "uninstalled_software", + "details": { + "host_id": 1, + "host_display_name": "Marko’s MacBook Pro", + "software_title": "Adobe Acrobat.app", + "script_execution_id": "ecf22dba-07dc-40a9-b122-5480e948b756", + "status": "uninstalled" + } + }, { "created_at": "2023-07-27T14:35:08Z", "id": 2, @@ -4610,6 +4664,23 @@ To wipe a macOS, iOS, iPadOS, or Windows host, the host must have MDM turned on. { "count": 3, "activities": [ + { + "created_at": "2023-07-27T14:35:08Z", + "actor_id": 1, + "actor_full_name": "Anna Chao", + "uuid": "cc081637-fdf9-4d44-929f-96dfaec00f67", + "actor_gravatar": "", + "actor_email": "", + "type": "uninstalled_software", + "fleet_initiated_activity": false, + "details": { + "host_id": 1, + "host_display_name": "Marko's MacBook Pro", + "software_title": "Adobe Acrobat.app", + "script_execution_id": "ecf22dba-07dc-40a9-b122-5480e948b756", + "status": "pending_uninstall", + } + }, { "created_at": "2023-07-27T14:35:08Z", "uuid": "d6cffa75-b5b5-41ef-9230-15073c8a88cf", @@ -6812,6 +6883,29 @@ Team policies work the same as policies, but at the team level. "failing_host_count": 0, "host_count_updated_at": "2023-12-20T15:23:57Z", "calendar_events_enabled": false + }, + { + "id": 3, + "name": "macOS - install/update Adobe Acrobat", + "query": "SELECT 1 FROM apps WHERE name = \"Adobe Acrobat.app\" AND bundle_short_version != \"24.002.21005\";", + "description": "Checks if the hard disk is encrypted on Windows devices", + "critical": false, + "author_id": 43, + "author_name": "Alice", + "author_email": "alice@example.com", + "team_id": 1, + "resolution": "Resolution steps", + "platform": "darwin", + "created_at": "2021-12-16T14:37:37Z", + "updated_at": "2021-12-16T16:39:00Z", + "passing_host_count": 2300, + "failing_host_count": 3, + "host_count_updated_at": "2023-12-20T15:23:57Z", + "calendar_events_enabled": false, + "install_software": { + "name": "Adobe Acrobat.app", + "software_title_id": 1234 + } } ], "inherited_policies": [ @@ -6993,6 +7087,7 @@ The semantics for creating a team policy are the same as for global policies, se | resolution | string | body | The resolution steps for the policy. | | platform | string | body | Comma-separated target platforms, currently supported values are "windows", "linux", "darwin". The default, an empty string means target all platforms. | | critical | boolean | body | _Available in Fleet Premium_. Mark policy as critical/high impact. | +| software_title_id | integer | body | _Available in Fleet Premium_. ID of software title to install if the policy fails. | Either `query` or `query_id` must be provided. @@ -7036,7 +7131,11 @@ Either `query` or `query_id` must be provided. "passing_host_count": 0, "failing_host_count": 0, "host_count_updated_at": null, - "calendar_events_enabled": false + "calendar_events_enabled": false, + "install_software": { + "name": "Adobe Acrobat.app", + "software_title_id": 1234 + } } } ``` @@ -7091,6 +7190,7 @@ Either `query` or `query_id` must be provided. | platform | string | body | Comma-separated target platforms, currently supported values are "windows", "linux", "darwin". The default, an empty string means target all platforms. | | critical | boolean | body | _Available in Fleet Premium_. Mark policy as critical/high impact. | | calendar_events_enabled | boolean | body | _Available in Fleet Premium_. Whether to trigger calendar events when policy is failing. | +| software_title_id | integer | body | _Available in Fleet Premium_. ID of software title to install if the policy fails. | #### Example @@ -7132,7 +7232,11 @@ Either `query` or `query_id` must be provided. "passing_host_count": 0, "failing_host_count": 0, "host_count_updated_at": null, - "calendar_events_enabled": true + "calendar_events_enabled": true, + "install_software": { + "name": "Adobe Acrobat.app", + "software_title_id": 1234 + } } } ``` @@ -8300,12 +8404,15 @@ Gets the result of a script that was executed. "host_timeout": false, "host_id": 1, "execution_id": "e797d6c6-3aae-11ee-be56-0242ac120002", - "runtime": 20 + "runtime": 20, + "created_at": "2024-09-11T20:30:24Z" } ``` > Note: `exit_code` can be `null` if Fleet hasn't heard back from the host yet. +> Note: `created_at` is the creation timestamp of the script execution request. + ### Add script Uploads a script, making it available to run on hosts assigned to the specified team (or no team). @@ -8539,6 +8646,7 @@ Deletes the session specified by ID. When the user associated with the session n - [Add package](#add-package) - [List App Store apps](#list-app-store-apps) - [Add App Store app](#add-app-store-app) +- [Add Fleet library app](#add-fleet-library-app) - [Install package or App Store app](#install-package-or-app-store-app) - [Get package install result](#get-package-install-result) - [Download package](#download-package) @@ -8854,14 +8962,17 @@ Returns information about the specified software. By default, `versions` are sor "installer_id": 23, "team_id": 3, "uploaded_at": "2024-04-01T14:22:58Z", - "install_script": "sudo installer -pkg /temp/FalconSensor-6.44.pkg -target /", + "install_script": "sudo installer -pkg '$INSTALLER_PATH' -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", + "uninstall_script": "/Library/CS/falconctl uninstall", "self_service": true, "status": { "installed": 3, - "pending": 1, - "failed": 2, + "pending_install": 1, + "failed_install": 0, + "pending_uninstall": 2, + "failed_uninstall": 1 } }, "app_store_app": null, @@ -9067,7 +9178,7 @@ Add a package (.pkg, .msi, .exe, .deb) to install on macOS, Windows, or Linux (U | ---- | ------- | ---- | -------------------------------------------- | | 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](https://github.com/fleetdm/fleet/tree/f71a1f183cc6736205510580c8366153ea083a8d/pkg/file/scripts) for each package type. | +| install_script | string | form | Script that Fleet runs to install software. If not specified Fleet runs [default install script](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. | @@ -9112,6 +9223,87 @@ Content-Type: application/octet-stream `Status: 200` +### Modify package + +_Available in Fleet Premium._ + +Update a package to install on macOS, Windows, or Linux (Ubuntu) hosts. + +`PATCH /api/v1/fleet/software/titles/:title_id/package` + +#### Parameters + +| Name | Type | In | Description | +| ---- | ------- | ---- | -------------------------------------------- | +| software | file | form | Installer package file. Supported packages are PKG, MSI, EXE, and DEB. | +| team_id | integer | form | **Required**. The team ID. Updates a software package in the specified team. | +| install_script | string | form | Command that Fleet runs to install software. If not specified Fleet runs the [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, the package will not be installed. | +| 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 | Whether this is optional self-service software that can be installed by the end user. | + +> Changes to the installer package will reset installation counts. Changes to any field other than `self_service` will cancel pending installs for the old package. +#### Example + +`PATCH /api/v1/fleet/software/titles/1/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="self_service" +true +--------------------------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` + +```json +{ + "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": 0, + "pending": 0, + "failed": 0 + } + } +} +``` + ### List App Store 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. @@ -9238,9 +9430,31 @@ _Available in Fleet Premium._ Install software (package or App Store app) on a macOS, iOS, iPadOS, Windows, or Linux (Ubuntu) host. Software title must have a `software_package` or `app_store_app` added to be installed. -> Note: Fleet's agent (fleetd) only installs software it has been asked to install, but technically has access to all installer executables. +`POST /api/v1/fleet/hosts/:id/software/:software_title_id/install` + +#### 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/3435/install` + +##### Default response + +`Status: 202` + +### Uninstall 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._ + +Uninstall software (package) on a macOS, Windows, or Linux (Ubuntu) host. Software title must have a `software_package` added to be uninstalled. -`POST /api/v1/fleet/hosts/:id/software/install/:software_title_id` +`POST /api/v1/fleet/hosts/:id/software/:software_title_id/uninstall` #### Parameters @@ -9251,7 +9465,7 @@ Install software (package or App Store app) on a macOS, iOS, iPadOS, Windows, or #### Example -`POST /api/v1/fleet/hosts/123/software/install/3435` +`POST /api/v1/fleet/hosts/123/software/3435/uninstall` ##### Default response @@ -9263,7 +9477,7 @@ Install software (package or App Store app) on a macOS, iOS, iPadOS, Windows, or _Available in Fleet Premium._ -`GET /api/v1/fleet/software/install/results/:install_uuid` +`GET /api/v1/fleet/software/install/:install_uuid/results` Get the results of a software package install. @@ -9275,7 +9489,7 @@ To get the results of an App Store app install, use the [List MDM commands](#lis #### Example -`GET /api/v1/fleet/software/install/results/b15ce221-e22e-4c6a-afe7-5b3400a017da` +`GET /api/v1/fleet/software/install/b15ce221-e22e-4c6a-afe7-5b3400a017da/results` ##### Default response diff --git a/website/config/routes.js b/website/config/routes.js index 8c9991200f3a..57d1c0608bd8 100644 --- a/website/config/routes.js +++ b/website/config/routes.js @@ -559,6 +559,7 @@ module.exports.routes = { 'GET /learn-more-about/host-identifiers': '/docs/rest-api/rest-api#get-host-by-identifier', 'GET /learn-more-about/uninstall-fleetd': '/docs/using-fleet/faq#how-can-i-uninstall-fleetd', 'GET /learn-more-about/vulnerability-processing': '/docs/using-fleet/vulnerability-processing', + 'GET /learn-more-about/dep-profile': 'https://developer.apple.com/documentation/devicemanagement/define_a_profile', 'GET /learn-more-about/apple-business-manager-tokens-api': '/docs/rest-api/rest-api#list-apple-business-manager-abm-tokens', 'GET /learn-more-about/apple-business-manager-teams-api': 'https://github.com/fleetdm/fleet/blob/main/docs/Contributing/API-for-contributors.md#update-abm-tokens-teams', 'GET /learn-more-about/apple-business-manager-gitops': '/docs/using-fleet/gitops#apple-business-manager',