diff --git a/articles/role-based-access.md b/articles/role-based-access.md index 72e39c0bb1ef..858ca1c92535 100644 --- a/articles/role-based-access.md +++ b/articles/role-based-access.md @@ -93,7 +93,7 @@ GitOps is an API-only and write-only role that can be used on CI/CD pipelines. | Edit [MDM settings](https://fleetdm.com/docs/using-fleet/mdm-macos-settings) | | | | ✅ | ✅ | | Edit [MDM settings for teams](https://fleetdm.com/docs/using-fleet/mdm-macos-settings) | | | | ✅ | ✅ | | View all [MDM settings](https://fleetdm.com/docs/using-fleet/mdm-macos-settings) | | | | ✅ | ✅ | -| Edit setup experience (end user authentication, bootstrap package, Setup Assistant)\* | | | ✅ | ✅ | ✅ | +| Edit [macOS setup experience]([https://fleetdm.com/docs/](https://fleetdm.com/guides/macos-setup-experience#basic-article))\* | | | ✅ | ✅ | ✅ | | Edit end user license agreement (EULA)\* | | | | ✅ | | | Run scripts on hosts | | | ✅ | ✅ | | | View saved scripts\* | ✅ | ✅ | ✅ | ✅ | | @@ -163,11 +163,7 @@ Users with access to multiple teams can be assigned different roles for each tea | Execute MDM commands on macOS and Windows hosts* | | | ✅ | ✅ | | | View results of MDM commands executed on macOS and Windows hosts* | ✅ | ✅ | ✅ | ✅ | | | Edit [team MDM settings](https://fleetdm.com/docs/using-fleet/mdm-macos-settings) | | | | ✅ | ✅ | -| View/download MDM macOS setup assistant | | | ✅ | ✅ | | -| Edit/upload MDM macOS setup assistant | | | ✅ | ✅ | ✅ | -| View metadata of MDM macOS bootstrap packages | | | ✅ | ✅ | | -| Edit/upload MDM macOS bootstrap packages | | | ✅ | ✅ | ✅ | -| Enable/disable MDM macOS setup end user authentication | | | ✅ | ✅ | ✅ | +| Edit [macOS setup experience]([https://fleetdm.com/docs/](https://fleetdm.com/guides/macos-setup-experience#basic-article))\* | | | ✅ | ✅ | ✅ | | Run scripts on hosts | | | ✅ | ✅ | | | View saved scripts | ✅ | ✅ | ✅ | ✅ | | | Edit/upload saved scripts | | | ✅ | ✅ | | diff --git a/docs/Configuration/yaml-files.md b/docs/Configuration/yaml-files.md index a2d2b09c0193..ab55368a46df 100644 --- a/docs/Configuration/yaml-files.md +++ b/docs/Configuration/yaml-files.md @@ -71,7 +71,7 @@ policies: package_path: "../lib/linux-firefox.deb.package.yml" ``` -`default.yml`, `teams/team-name.yml`, or `teams/no-team.yml` +`default.yml` (for policies that neither install software nor run scripts), `teams/team-name.yml`, or `teams/no-team.yml` ```yaml policies: @@ -241,6 +241,10 @@ controls: bootstrap_package: https://example.org/bootstrap_package.pkg enable_end_user_authentication: true macos_setup_assistant: ../lib/dep-profile.json + script: ../lib/macos-setup-script.sh + software: + - app_store_id: '1091189122' + - package_path: ../lib/software/adobe-acrobat.software.yml macos_migration: # Available in Fleet Premium enable: true mode: voluntary @@ -284,6 +288,8 @@ The `macos_setup` section lets you control the out-of-the-box macOS [setup exper - `bootstrap_package` is the URL to a bootstap package. Fleet will download the bootstrap package (default: `""`). - `enable_end_user_authentication` specifies whether or not to require end user authentication when the user first sets up their macOS host. - `macos_setup_assistant` is a path to a custom automatic enrollment (ADE) profile (.json). +- `script` is the path to a custom setup script to run after the host is first set up. +- `software` is a list of references to either a `package_path` matching a package in the `software` section below or an `app_store_id` to install when the host is first set up. ### macos_migration @@ -293,7 +299,7 @@ The `macos_migration` section lets you control the [end user migration workflow] - `mode` specifies whether the end user initiates migration (`voluntary`) or they're nudged every 15-20 minutes to migrate (`forced`) (default: `""`). - `webhook_url` is the URL that Fleet sends a webhook to when the end user selects **Start**. Receive this webhook using your automation tool (ex. Tines) to unenroll your end users from your old MDM solution. -Can only be configure for all teams (`default.yml`). +Can only be configured for all teams (`default.yml`). ## software @@ -432,8 +438,9 @@ org_settings: - `live_query_disabled` disables the ability to run live queries (ad hoc queries executed via the UI or fleetctl) (default: `false`). - `query_reports_disabled` disables query reports and deletes existing repors (default: `false`). - `query_report_cap` sets the maximum number of results to store per query report before the report is clipped. If increasing this cap, we recommend enabling reports for one query at time and monitoring your infrastructure. (Default: `1000`) -- `scripts_disabled` blocks access to run scripts. Scripts may still be added in the UI and CLI (default: `false`). -- `server_url` is the base URL of the Fleet instance (default: provided during Fleet setup) +- `scripts_disabled` blocks access to run scripts. Scripts may still be added in the UI and CLI (defaul: `false`). +- `server_url` is the base URL of the Fleet instance. If this URL changes and Apple (macOS, iOS, iPadOS) hosts already have MDM turned on, the end users will have to turn MDM off and back on to use MDM features. (default: provided during Fleet setup) + Can only be configured for all teams (`org_settings`). @@ -669,6 +676,22 @@ Once the IdP settings are configured, you can use the [`controls.macos_setup.ena Can only be configured for all teams (`org_settings`). +##### apple_server_url + +Update this URL if you're self-hosting Fleet and you want your hosts to talk to this URL for MDM features. (If not configured, hosts will use the base URL of the Fleet instance.) + +If this URL changes and hosts already have MDM turned on, the end users will have to turn MDM off and back on to use MDM features. + +##### Example + +```yaml +org_settings: + mdm: + apple_server_url: https://instance.fleet.com +``` + +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 0e43394e6da7..1a375bd0816d 100644 --- a/docs/Contributing/API-for-contributors.md +++ b/docs/Contributing/API-for-contributors.md @@ -6,6 +6,7 @@ - [Live query](#live-query) - [Trigger cron schedule](#trigger-cron-schedule) - [Device-authenticated routes](#device-authenticated-routes) +- [Orbit-authenticated routes](#orbit-authenticated-routes) - [Downloadable installers](#downloadable-installers) - [Setup](#setup) - [Scripts](#scripts) @@ -3196,6 +3197,82 @@ Notifies the server about an agent error, resulting in two outcomes: --- +## Orbit-authenticated routes + +- [Get the status of a device in the setup experience](#get-the-status-of-a-device-in-the-setup-experience) + + +### Get the status of a device in the setup experience + +`POST /api/fleet/orbit/setup_experience/status` + +##### Parameters + +| Name | Type | In | Description | +| ----- | ------ | ---- | ---------------------------------- | +| orbit_node_key | string | body | The Orbit's node key for authentication. | +| force_release | boolean | body | Force a host release from ADE flow, in case the setup is taking too long. | + + +##### Example + +`POST /api/v1/fleet/device/8b49859b-1ffa-483d-ad27-85b30aa3c55f/setup_experience/status` + +##### Request body + +```json +{ + "orbit_node_key":"FbvSsWfTRwXEecUlCBTLmBcjGFAdzqd/", + "force_release":false +} +``` + +##### Default response + +`Status: 200` + +```json +{ + "setup_experience_results": { + "script": { + "name": "setup_script.sh", + "status": "success", + "execution_id": "b16fdd31-71cc-4258-ab27-744490809ebd" + }, + "software": [ + { + "name": "Zoom Workplace", + "status": "success", + "software_title_id": 957 + }, + { + "name": "Bear: Markdown Notes", + "status": "success", + "software_title_id": 287 + }, + { + "name": "Evernote", + "status": "success", + "software_title_id": 1313 + } + ], + "configuration_profiles": [ + { + "profile_uuid": "ae6a9efd5-9166-11ef-83af-0242ac12000b", + "name": "Fleetd configuration", + "status": "verified" + }, + { + "profile_uuid": "ae6aa8108-9166-11ef-83af-0242ac12000b", + "name": "Fleet root certificate authority (CA)", + "status": "verified" + } + ], + "org_logo_url": "" + } +} + +``` ## Downloadable installers diff --git a/docs/REST API/rest-api.md b/docs/REST API/rest-api.md index e23fdb148334..e652789f3420 100644 --- a/docs/REST API/rest-api.md +++ b/docs/REST API/rest-api.md @@ -848,7 +848,7 @@ None. "contact_url": "https://fleetdm.com/company/contact" }, "server_settings": { - "server_url": "https://localhost:8080", + "server_url": "https://instance.fleet.com", "enable_analytics": true, "live_query_disabled": false, "query_reports_disabled": false, @@ -946,7 +946,8 @@ None. "enable_end_user_authentication": false, "macos_setup_assistant": "path/to/config.json", "enable_release_device_manually": true - } + }, + "client_url": "https://instance.fleet.com" }, "agent_options": { "spec": { @@ -1140,7 +1141,7 @@ Modifies the Fleet's configuration with the supplied information. "contact_url": "https://fleetdm.com/company/contact" }, "server_settings": { - "server_url": "https://localhost:8080", + "server_url": "https://instance.fleet.com", "enable_analytics": true, "live_query_disabled": false, "query_reports_disabled": false, @@ -1245,7 +1246,8 @@ Modifies the Fleet's configuration with the supplied information. "bootstrap_package": "", "enable_end_user_authentication": false, "macos_setup_assistant": "path/to/config.json" - } + }, + "apple_server_url": "https://instance.fleet.com" }, "agent_options": { "config": { @@ -1748,6 +1750,9 @@ Setting `integrations.ndes_scep_proxy` to `null` will clear existing settings. N | macos_setup | object | See [`mdm.macos_setup`](#mdm-macos-setup). | | macos_settings | object | See [`mdm.macos_settings`](#mdm-macos-settings). | | windows_settings | object | See [`mdm.windows_settings`](#mdm-windows-settings). | +| apple_server_url | string | Update this URL if you're self-hosting Fleet and you want your hosts to talk to this URL for MDM features. (If not configured, hosts will use the base URL of the Fleet instance.) | + +> Note: If `apple_server_url` changes and Apple (macOS, iOS, iPadOS) hosts already have MDM turned on, the end users will have to turn MDM off and back on to use MDM features.
@@ -2540,6 +2545,8 @@ the `software` table. | os_settings_disk_encryption | string | query | Filters the hosts by the status of the disk encryption setting applied to the hosts. 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 | boolean | query | If `true`, the response will include a list of installed software for each host, including vulnerability data. (Note that software lists can be large, so this may cause significant CPU and RAM usage depending on page size and request concurrency.) | | 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. @@ -2559,7 +2566,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 @@ -2705,6 +2712,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" + } ] } ] @@ -4271,7 +4329,7 @@ Resends a configuration profile for the specified host. | ---- | ------- | ---- | ---------------------------- | | id | integer | path | **Required**. The host's ID. | | query | string | query | Search query keywords. Searchable fields include `name`. | -| available_for_install | boolean | query | If `true` or `1`, only list software that is available for install (added by the user). Default is `false`. +| available_for_install | boolean | query | If `true` or `1`, only list software that is available for install (added by the user). Default is `false`. | | page | integer | query | Page number of the results to fetch.| | per_page | integer | query | Results per page.| @@ -5773,6 +5831,11 @@ Get aggregate status counts of profiles for to macOS and Windows hosts that are - [Get metadata about an EULA file](#get-metadata-about-an-eula-file) - [Delete an EULA file](#delete-an-eula-file) - [Download an EULA file](#download-an-eula-file) +- [List software (setup experience)](#list-software-setup-experience) +- [Update software (setup experience)](#update-software-setup-experience) +- [Add script (setup experience)](#add-script-setup-experience) +- [Get or download script (setup experience)](#get-or-download-script-setup-experience) +- [Delete script (setup experience)](#delete-script-setup-experience) @@ -6292,6 +6355,219 @@ Content-Length: Body: ``` +### List software (setup experience) + +_Available in Fleet Premium_ + +List software that can or will be automatically installed during macOS setup. If `install_during_setup` is `true` it will be installed during setup. + +`GET /api/v1/fleet/setup_experience/software` + +| Name | Type | In | Description | +| ----- | ------ | ----- | ---------------------------------------- | +| team_id | integer | query | _Available in Fleet Premium_. The ID of the team to filter software by. If not specified, it will filter only software that's available to hosts with no team. | +| page | integer | query | Page number of the results to fetch. | +| per_page | integer | query | Results per page. | + + +#### Example + +`GET /api/v1/fleet/setup_experience/software?team_id=3` + +##### Default response + +`Status: 200` + +```json +{ + "software_titles": [ + { + "id": 12, + "name": "Firefox.app", + "software_package": { + "name": "FirefoxInsall.pkg", + "version": "125.6", + "self_service": true, + "install_during_setup": true + }, + "app_store_app": null, + "versions_count": 3, + "source": "apps", + "browser": "", + "hosts_count": 48, + "versions": [ + { + "id": 123, + "version": "1.12", + "vulnerabilities": ["CVE-2023-1234","CVE-2023-4321","CVE-2023-7654"] + }, + { + "id": 124, + "version": "3.4", + "vulnerabilities": ["CVE-2023-1234","CVE-2023-4321","CVE-2023-7654"] + }, + { + "id": 12 + "version": "1.13", + "vulnerabilities": ["CVE-2023-1234","CVE-2023-4321","CVE-2023-7654"] + } + ] + } + ], + { + "count": 2, + "counts_updated_at": "2024-10-04T10:00:00Z", + "meta": { + "has_next_results": false, + "has_previous_results": false + } + }, +} +``` + +### Update software (setup experience) + +_Available in Fleet Premium_ + +Set software that will be automatically installed during macOS setup. Software that isn't included in the request will be unset. + +`PUT /api/v1/fleet/setup_experience/software` + +| Name | Type | In | Description | +| ----- | ------ | ----- | ---------------------------------------- | +| team_id | integer | query | _Available in Fleet Premium_. The ID of the team to set the software for. If not specified, it will set the software for hosts with no team. | +| software_title_ids | array | body | The ID of software titles to install during macOS setup. | + +#### Example + +`PUT /api/v1/fleet/setup_experience/software?team_id=3` + +##### Default response + +`Status: 200` + +```json +{ + "software_title_ids": [23,3411,5032] +} +``` + +### Add script (setup experience) + +_Available in Fleet Premium_ + +Add a script that will automatically run during macOS setup. + +`POST /api/v1/fleet/setup_experience/script` + +| Name | Type | In | Description | +| ----- | ------ | ----- | ---------------------------------------- | +| team_id | integer | form | _Available in Fleet Premium_. The ID of the team to add the script to. If not specified, a script will be added for hosts with no team. | +| script | file | form | The ID of software titles to install during macOS setup. | + +#### Example + +`POST /api/v1/fleet/setup_experience/script` + +##### Default response + +`Status: 200` + +##### Request headers + +```http +Content-Length: 306 +Content-Type: multipart/form-data; boundary=------------------------f02md47480und42y +``` + +##### Request body + +```http +--------------------------f02md47480und42y +Content-Disposition: form-data; name="team_id" + +1 +--------------------------f02md47480und42y +Content-Disposition: form-data; name="script"; filename="myscript.sh" +Content-Type: application/octet-stream + +echo "hello" +--------------------------f02md47480und42y-- + +``` + +### Get or download script (setup experience) + +_Available in Fleet Premium_ + +Get a script that will automatically run during macOS setup. + +`GET /api/v1/fleet/setup_experience/script` + +| Name | Type | In | Description | +| ----- | ------ | ----- | ---------------------------------------- | +| team_id | integer | query | _Available in Fleet Premium_. The ID of the team to get the script for. If not specified, script will be returned for hosts with no team. | +| alt | string | query | If specified and set to "media", downloads the script's contents. | + + +#### Example (get script) + +`GET /api/v1/fleet/setup_experience/script?team_id=3` + +##### Default response + +`Status: 200` + +```json +{ + "id": 1, + "team_id": 3, + "name": "setup-experience-script.sh", + "created_at": "2023-07-30T13:41:07Z", + "updated_at": "2023-07-30T13:41:07Z" +} +``` + +#### Example (download script) + +`GET /api/v1/fleet/setup_experience/script?team_id=3?alt=media` + +##### Example response headers + +```http +Content-Length: 13 +Content-Type: application/octet-stream +Content-Disposition: attachment;filename="2023-09-27 script_1.sh" +``` + +###### Example response body + +`Status: 200` + +``` +echo "hello" +``` + +### Delete script (setup experience) + +_Available in Fleet Premium_ + +Delete a script that will automatically run during macOS setup. + +`DELETE /api/v1/fleet/setup_experience/script` + +| Name | Type | In | Description | +| ----- | ------ | ----- | ---------------------------------------- | +| team_id | integer | query | _Available in Fleet Premium_. The ID of the team to get the script for. If not specified, script will be returned for hosts with no team. | + +#### Example + +`DELETE /api/v1/fleet/setup_experience/script?team_id=3` + +##### Default response + +`Status: 200` + --- ## Commands @@ -7416,7 +7692,7 @@ Returns a list of global queries or team queries. | order_direction | string | query | **Requires `order_key`**. The direction of the order given the order key. Options include `asc` and `desc`. Default is `asc`. | | team_id | integer | query | _Available in Fleet Premium_. The ID of the parent team for the queries to be listed. When omitted, returns global queries. | | query | string | query | Search query keywords. Searchable fields include `name`. | -| merge_inherited | boolean | query | _Available in Fleet Premium_. If `true`, will include global queries in addition to team queries when filtering by `team_id`. (If no `team_id` is provided, this parameter is ignored.) +| merge_inherited | boolean | query | _Available in Fleet Premium_. If `true`, will include global queries in addition to team queries when filtering by `team_id`. (If no `team_id` is provided, this parameter is ignored.) | #### Example @@ -8827,6 +9103,7 @@ Get a list of all software. | min_cvss_score | integer | query | _Available in Fleet Premium_. Filters to include only software with vulnerabilities that have a CVSS version 3.x base score higher than the specified value. | | 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 by platform. Supported values are `darwin`, `windows`, and `linux`. | #### Example @@ -9336,6 +9613,7 @@ Add a package (.pkg, .msi, .exe, .deb, .rpm) to install on macOS, Windows, or Li | 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. | + #### Example `POST /api/v1/fleet/software/package` diff --git a/handbook/company/pricing-features-table.yml b/handbook/company/pricing-features-table.yml index d2489823663f..78f331439047 100644 --- a/handbook/company/pricing-features-table.yml +++ b/handbook/company/pricing-features-table.yml @@ -1109,6 +1109,16 @@ jamfProHasFeature: yes jamfProtectHasFeature: no # System for Cross-domain Identity Management (SCIM) provisioning comingSoonOn: 2024-12-31 #customer-rosner, https://github.com/fleetdm/fleet/issues/15671 +- industryName: Grant Wi-Fi access + description: Help your end users connect to Wi-Fi by adding your Simple Certificate Enrollment Protocol (SCEP) server. + # documentationUrl: TODO + isExperimental: yes + productCategories: [Device management] + pricingTableCategories: [Integrations] + usualDepartment: IT + tier: Premium + jamfProHasFeature: yes + jamfProtectHasFeature: no # # ╔╦╗╦ ╦╦╦═╗╔╦╗ ╔═╗╔═╗╦═╗╔╦╗╦ ╦ ╔═╗╦ ╦╔╦╗╔═╗╔╦╗╔═╗╔╦╗╦╔═╗╔╗╔ # ║ ╠═╣║╠╦╝ ║║───╠═╝╠═╣╠╦╝ ║ ╚╦╝ ╠═╣║ ║ ║ ║ ║║║║╠═╣ ║ ║║ ║║║║