diff --git a/articles/deploy-security-agents.md b/articles/deploy-security-agents.md deleted file mode 100644 index 20d6cd28abec..000000000000 --- a/articles/deploy-security-agents.md +++ /dev/null @@ -1,97 +0,0 @@ -# Deploy security agents - -![Deploy security agents](../website/assets/images/articles/deploy-security-agents-1600x900@2x.png) - -Fleet [v4.50.0](https://github.com/fleetdm/fleet/releases/tag/fleet-v4.50.0) introduced the ability to upload and deploy security agents to your hosts. Beyond a [bootstrap package](https://fleetdm.com/docs/using-fleet/mdm-macos-setup-experience#bootstrap-package) at enrollment, deploying security agents allows you to specify and verify device configuration using a pre-enrollment osquery query and customization of the install and post-install scripts, allowing for key and license deployment and configuration. This guide will walk you through the steps to upload, configure, and install a security agent to hosts in your fleet. - -## Prerequisites - -* Fleet [v4.50.0](https://github.com/fleetdm/fleet/releases/tag/fleet-v4.50.0). -* `fleetd` 1.25.0 deployed via MDM or built with the `--scripts-enabled` flag. -* An S3 bucket [configured](https://fleetdm.com/docs/configuration/fleet-server-configuration#s-3-software-installers-bucket) to store the installers. -* Increase any load balancer timeouts to at least 5 minutes for the following endpoints: - * [Add software](https://fleetdm.com/docs/rest-api/rest-api#add-software). - * [Batch-apply software](https://fleetdm.com/docs/rest-api/rest-api#add-software). - -## Step-by-step instructions - -### Access security agent installers - -To access and manage security agents in Fleet: - -* **Navigate to the Software page**: Click on the "Software" tab in the main navigation menu. -* **Select a team**: Click on the dropdown at the top left of the page. -* **Find your software**: using the filters on the top of the table, you can choose between: - * “Available for install” filters software that can be installed on your hosts. - * “Self-service” filters software that end users can install from Fleet Desktop. -* **Select security agent installer**: Click on a software package to view details and access additional actions for the agent installer. - -### Add a security agent to a team - -* **Navigate to the Software page**: Click on the "Software" tab in the main navigation menu. -* **Select a team**: Select a team or the "No team" team to add a security agent. - -> Security agents cannot be added to "All teams" - -* Click the “Add Software” button in the top right corner, and a modal will appear. -* Choose a file to upload. `.pkg`, `.msi`, `.exe`, or `.deb` files are supported. -* After selecting a file, a default install script will be pre-filled. If the security agent requires a custom installation process, this script can be edited. -* To allow users to install the software from Fleet Desktop, check the “Self-service” checkbox. -* To customize the conditions, click on “Advanced options”: - * **Pre-install condition**: A pre-install condition is a valid osquery SQL statement that will be evaluated on the host before installing the software. If provided, the installation will proceed only if the query returns any value. - * **Post-install script** A post-install script will run after the installation is complete, allowing you to configure the security agent right after installation. If this script returns a non-zero exit code, the installation will fail, and `fleetd` will attempt to uninstall the software. - -### Install a security agent on a host - -After an installer is added to a team, it can be installed on hosts via the UI. - -* **Navigate to the Hosts page**: Click on the "Hosts" tab in the main navigation menu. -* **Navigate to the Host details page**: Click the host you want to install the security agent. -* **Navigate to the Host software tab**: In the host details, search for the tab named “Software” -* **Find your security agent**: Use the search bar and filters to search for your security agent. -* **Install the security agent on the host**: In the leftmost row of the table, click on “Actions” > “Install.” -* **Track installation status**: by either - * Checking the “Install status” in the host software table. - * Navigate to the “Details” tab on the host details page and check the activity log. - -### Edit a security agent - -Security agent installers can’t be edited via the UI. To modify an installer, remove it from the UI and add a new one. - -### Remove a security agent from a team - -* **Navigate to the Software page**: Click on the "Software" tab in the main navigation menu. -* **Select a team**: Select a team or the "No team" team to add a security agent. -* **Find your software**: using the filters on the top of the table, you can choose between: - * “Available for install” filters software can be installed on your hosts. - * “Self-service” filters software that users can install from Fleet Desktop. -* **Select security agent installer**: Click on a software package to view details. -* **Remove security agent installer**: From the Actions menu, select "Delete." Click the "Delete" button on the modal. - -> Removing a security agent from a team will not uninstall the agent from the existing host(s). - -### Manage security agents with the REST API - -Fleet also provides a REST API for managing software programmatically. The API allows you to add, update, retrieve, list, and delete software. Detailed documentation on Fleet's [REST API is available](https://fleetdm.com/docs/rest-api/rest-api#software). - -### Manage security agents with GitOps - -Installers for security agents can be managed via `fleetctl` using [GitOps](https://fleetdm.com/docs/using-fleet/gitops). - -Please refer to the documentation specific to [managing software with GitOps](https://fleetdm.com/docs/using-fleet/gitops#software). For a real-world example, [see how we manage software at Fleet](https://github.com/fleetdm/fleet/tree/main/it-and-security/teams). - - -## Conclusion - -Deploying security agents with Fleet is straightforward and ensures your hosts are protected with the latest security measures. This guide has shown you how to access, add, and install security agents, as well as manage them using the REST API and `fleetctl`. Following these steps can effectively equip your fleet with the necessary security tools. - -See Fleet's [documentation](https://fleetdm.com/docs/using-fleet) and additional [guides](https://fleetdm.com/guides) for more details on advanced setups, software features, and vulnerability detection. - - - - - - - - - diff --git a/articles/deploy-software-packages.md b/articles/deploy-software-packages.md new file mode 100644 index 000000000000..92aa0901ccf1 --- /dev/null +++ b/articles/deploy-software-packages.md @@ -0,0 +1,177 @@ +# Deploy software packages + +![Deploy software](../website/assets/images/articles/deploy-security-agents-1600x900@2x.png) + +Fleet [v4.50.0](https://github.com/fleetdm/fleet/releases/tag/fleet-v4.50.0) introduced the ability to upload and deploy software to your hosts. Fleet [v4.57.0](https://github.com/fleetdm/fleet/releases/tag/fleet-v4.57.0) added the ability to include an uninstall script and edit software details. Beyond a [bootstrap package](https://fleetdm.com/docs/using-fleet/mdm-macos-setup-experience#bootstrap-package) at enrollment, deploying software allows you to specify and verify device configuration using a pre-install query and customization of the install, post-install, and uninstall scripts, allowing for key and license deployment and configuration. Admins can modify these options and settings after the initial upload. This guide will walk you through the steps to upload, configure, install, and uninstall a software package to hosts in your fleet. + +## Prerequisites + +* Fleet [v4.57.0](https://github.com/fleetdm/fleet/releases/tag/fleet-v4.57.0). + +* `fleetd` 1.25.0 deployed via MDM or built with the `--scripts-enabled` flag. + +> `fleetd` prior to 1.33.0 will use a hard-coded uninstall script to clean up from a failed install. As of 1.33.0, the (default or customized) uninstall script will be used to clean up failed installs. + +* An S3 bucket [configured](https://fleetdm.com/docs/configuration/fleet-server-configuration#s-3-software-installers-bucket) to store the installers. + +* Increase any load balancer timeouts to at least 5 minutes for the [Add software](https://fleetdm.com/docs/rest-api/rest-api#add-software) endpoint. + +## Step-by-step instructions + +### Access software packages + +To access and manage software in Fleet: + +* **Navigate to the Software page**: Click on the "Software" tab in the main navigation menu. + +* **Select a team**: Click on the dropdown at the top left of the page. + +> Software packages are tied to a specific team. This allows you to, for example, test a newer release of an application within your IT team before rolling it out to the rest of your organization, or deploy the appropriate architecture-specific installer to both Intel and Apple Silicon Macs. + +* **Find your software**: using the filters on the top of the table, you can choose between: + + * “Available for install” filters software that can be installed on your hosts. + + * “Self-service” filters software that end users can install from Fleet Desktop. + +* **Select software package**: Click on a software package to view details and access additional actions for the software. + +### Add a software package to a team + +* **Navigate to the Software page**: Click on the "Software" tab in the main navigation menu. + +* **Select a team**: Select a team "No team" to add a software package. + +> Software cannot be added to "All teams." + +* Click the “Add Software” button in the top right corner, and a dialog will appear. + +* Choose a file to upload. `.pkg`, `.msi`, `.exe`, and `.deb` files are supported. + +> Software installer uploads will fail if Fleet is unable to extract information from the installer package such bundle ID and version number. + +* To allow users to install the software from Fleet Desktop, check the “Self-service” checkbox. + +* To customize installer behavior, click on “Advanced options.” + +> After the initial package upload, all options can be modified, including the self-service setting, pre-install query, scripts, and even the software package file. When replacing an installer package, the replacement package must be the same type and for the same software as the original package. + +#### Pre-install query + +A pre-install query is a valid osquery SQL statement that will be evaluated on the host before installing the software. If provided, the installation will proceed only if the query returns any value. + +#### Install script + +After selecting a file, a default install script will be pre-filled. If the software package requires a custom installation process (for example, if [an EXE-based Windows installer requires custom handling](https://fleetdm.com/learn-more-about/exe-install-scripts)), this script can be edited. When the script is run, the `$INSTALLER_PATH` environment variable will be set by `fleetd` to where the installer is being run. + +#### Post-install script + +A post-install script will run after the installation, allowing you to, for example, configure the security agent right after installation. If this script returns a non-zero exit code, the installation will fail, and `fleetd` will attempt to uninstall the software. + +#### Uninstall script + +An uninstall script will run when an admin chooses to uninstall the software from the host on the host details page, or if an install fails for hosts running `fleetd` 1.33.0 or later. Like the install script, a default uninstall script will be pre-filled after selecting a file. This script can be edited if the software package requires a custom uninstallation process. + +In addition to the `$INSTALLER_PATH` environment variable supported by install scripts, you can use `$PACKAGE_ID` in uninstall scripts as a placeholder for the package IDs (for .pkg files), package name (for Linux installers), product code (for MSIs), or software name (for EXE installers). The Fleet server will substitute `$PACKAGE_ID` on upload. + +### Install a software package on a host + +After a software package is added to a team, it can be installed on hosts via the UI. + +* **Navigate to the Hosts page**: Click on the "Hosts" tab in the main navigation menu. + +* **Navigate to the Host details page**: Click the host you want to install the software package. + +* **Navigate to the Host software tab**: In the host details, search for the tab named “Software.” + +* **Find your software package**: Use the dropdown to select software “Available for install” or use the search bar to search for your software package by name. + +* **Install the software package on the host**: In the rightmost column of the table, click on “Actions” > “Install.” Installation will happen automatically or when the host comes online. + +* **Track installation status**: by either + + * Checking the status column in the host software table. + + * Navigate to the “Details” tab on the host details page and check the activity log. + +### Edit a software package + +* **Navigate to the Software page**: Click on the "Software" tab in the main navigation menu. + +* **Select a team**: Select a team (or "No team") to switch to the team whose software you want to edit. + +* **Find your software**: using the filters on the top of the table, you can choose between: + + * “Available for install” filters software can be installed on your hosts. + + * “Self-service” filters software that users can install from Fleet Desktop. + +* **Select software package**: Click on a software package to view details. + +* **Edit software package**: From the Actions menu, select "Edit." + +> Editing the pre-install query, install script, post-install script, or uninstall script cancels all pending installations and uninstallations for that package, except for installs and uninstalls that are currently running on a host. If a new software package is uploaded, in addition to canceling pending installs and uninstalls, host counts (for installs and pending and failed installs and uninstalls) will be reset to zero, so counts reflect the currently uploaded version of the package. + +### Uninstall a software package on a host + +After a software package is installed on a host, it can be uninstalled on the host via the UI. + +* **Navigate to the Hosts page**: Click on the "Hosts" tab in the main navigation menu. + +* **Navigate to the Host details page**: Click the host you want to uninstall the software package. + +* **Navigate to the Host software tab**: In the host details, search for the tab named “Software.” + +* **Find your software package**: Use the dropdown to select software “Available for install” or use the search bar to search for your software package by name. + +* **Uninstall the software package from the host**: In the rightmost column of the table, click on “Actions” > “Uninstall.” Uninstallation will happen automatically or when the host comes online. + +* **Track uninstallation status**: by either + + * Checking the status column in the host software table. + + * Navigate to the “Details” tab on the host details page and check the activity log. + +### Remove a software package from a team + +* **Navigate to the Software page**: Click on the "Software" tab in the main navigation menu. + +* **Select a team**: Select a team (or "No team") to switch to the team whose software you want to remove. + +* **Find your software**: using the filters on the top of the table, you can choose between: + + * “Available for install” filters software can be installed on your hosts. + + * “Self-service” filters software that users can install from Fleet Desktop. + +* **Select software package**: Click on a software package to view details. + +* **Remove software package**: From the Actions menu, select "Delete." Click the "Delete" button on the dialog. + +> Removing a software package from a team will cancel pending installs for hosts that are not in the middle of installing the software but will not uninstall the software from hosts where it is already installed. + +### Manage software with the REST API + +Fleet also provides a REST API for managing software programmatically. The API allows you to add, update, retrieve, list, and delete software. Detailed documentation on Fleet's [REST API is available]([https://fleetdm.com/docs/rest-api/rest-api#software](https://fleetdm.com/docs/rest-api/rest-api#software)), including endpoints for installing and uninstalling packages. + +### Manage software with GitOps + +Software packages can be managed via `fleetctl` using [GitOps](https://fleetdm.com/docs/using-fleet/gitops). + +Please refer to the documentation for [managing software with GitOps](https://fleetdm.com/docs/using-fleet/gitops#software), for a real-world example, [see how we manage software at Fleet](https://github.com/fleetdm/fleet/tree/main/it-and-security/teams). + +> When managing software installers via GitOps, the Fleet server receiving GitOps requests (**not** the machine running fleetctl as part of the GitOps workflow) will download installers from the specified URLs directly. + +## Conclusion + +Managing software with Fleet is straightforward and ensures your hosts are equipped with the latest tools. This guide has outlined how to access, add, edit, and remove software packages from a team, install and uninstall from specific hosts, and use the REST API and `fleetctl` to manage software packages. By following these steps, you can effectively maintain software packages across your fleet. + +For more information on advanced setups and features, explore Fleet’s [documentation](https://fleetdm.com/docs/using-fleet) and additional [guides](https://fleetdm.com/guides). + + + + + + + + diff --git a/articles/enable-okta-verify-on-macOS-with-configuration-profile.md b/articles/enable-okta-verify-on-macOS-with-configuration-profile.md new file mode 100644 index 000000000000..19bd9c5c9ef4 --- /dev/null +++ b/articles/enable-okta-verify-on-macOS-with-configuration-profile.md @@ -0,0 +1,130 @@ +# Enable Okta Verify on macOS using configuration profile + +## Introduction + +This guide will show you how to install [Okta Verify](https://help.okta.com/en-us/content/topics/mobile/okta-verify-overview.htm) on your macOS hosts and set them as managed by issuing a SCEP certificate via a configuration profile [managed through Fleet](https://fleetdm.com/guides/custom-os-settings). + +By following these steps, you can automate the deployment of Okta Verify across your devices. This will allow you to enforce multifactor authentication policies, improve device security, and manage user access seamlessly. + +## Prerequisites + +* MDM enabled and configured + +## Step-by-Step Instructions + +### **Step 1: Install Okta Verify on your hosts** + +Okta Verify can be installed: + +* As a Volume Purchasing Program (VPP) application, follow [these steps to install VPP apps](https://fleetdm.com/guides/install-vpp-apps-on-macos-using-fleet). +* As a *.pkg *file download the [installer from Okta](https://help.okta.com/oie/en-us/content/topics/identity-engine/devices/ov-install-options-macos.htm) and [deploy the installer using Fleet](https://fleetdm.com/guides/deploy-security-agents). + +After installing Okta Verify on the host, the device will be registered in Okta. + +### **Step 2: Issue a SCEP certificate for management attestation** + +The next step to ensure Okta detects the device as managed is to issue a SCEP certificate. + +* Follow the instructions on the Okta documentation to [configure a certificate authority](https://help.okta.com/oie/en-us/content/topics/identity-engine/devices/configure-ca-main.htm) using a **static** SCEP challenge. +* In your text editor, copy and paste the following configuration profile and edit the relevant values: + * `[REPLACE_WITH_CHALLENGE] `with the SCEP challenge you generated in the previous step. + * `[REPLACE_WITH_URL]`with the URL to your SCEP server. + * Adjust the `CN `value according to your organization's needs. You can use any of the [profile variables](https://support.apple.com/en-my/guide/deployment/dep04666af94/1/web/1.0) to uniquely identify your device. In the example `%ComputerName%` `managementAttestation` `%HardwareUUID%,` the certificate Common Name (CN) will contain both the computer name and the hardware UUID. + +```xml + + + + + + PayloadVersion + 1 + PayloadType + Configuration + PayloadIdentifier + Ignored + PayloadUUID + Ignored + PayloadDisplayName + SCEP device attestation + PayloadContent + + + PayloadContent + + Key Type + RSA + Challenge + [REPLACE_WITH_CHALLENGE] + Key Usage + 1 + Keysize + 2048 + URL + [REPLACE_WITH_URL] + AllowAllAppsAccess + + KeyIsExtractable + + Subject + + + + O + Fleet + + + + + CN + %ComputerName% managementAttestation %HardwareUUID% + + + + + PayloadIdentifier + com.apple.security.scep.C2D94E67-4F1A-4A3C-8142-7523A8D35713 + PayloadType + com.apple.security.scep + PayloadUUID + 632289FA-C3E0-481A-A417-BF40012FB729 + PayloadVersion + 1 + + + + + +``` + +* Enforce the configuration profile on your hosts. You can follow [this guide on enforcing custom OS settings in Fleet](https://fleetdm.com/guides/custom-os-settings). +* You can optionally verify the issued certificate by opening Keychain Access on the device or by running a [live query](https://fleetdm.com/guides/get-current-telemetry-from-your-devices-with-live-queries): + +```sql +SELECT * FROM certificates where common_name like '%managementAttestation%'; +``` + +### **Step 3: Configure device management in Okta** + +With Okta Verify installed and an attestation certificate in place, all left is to configure Okta and the device for device management, useful links from the Okta documentation are: + +* [Managed devices](https://help.okta.com/oie/en-us/content/topics/identity-engine/devices/managed-main.htm) +* [Enable and configure Okta Verify](https://help.okta.com/en-us/content/topics/mobile/okta-verify-overview.htm) + +Make sure the device is properly set up in Okta and that the user has used Okta FastPass at least once to see it as managed on the Okta dashboard. + +## Conclusion + +This guide covered how to install Okta Verify on your macOS hosts, issue a SCEP certificate for management attestation, and configure device management in Okta. By automating this process through Fleet, you can enforce multi-factor authentication, improve device security, and ensure that devices accessing your organization’s resources are properly managed. + +For more detailed information on managing devices and using Okta Verify, explore the Okta documentation and Fleet’s guides to optimize your device management strategy further. + +See Fleet's [documentation](https://fleetdm.com/docs/using-fleet) and additional [guides](https://fleetdm.com/guides) for more details on advanced setups, software features, and vulnerability detection. + + + + + + + + diff --git a/articles/enroll-byod-ios-ipados-hosts.md b/articles/enroll-byod-ios-ipados-hosts.md new file mode 100644 index 000000000000..31c070b2d5e7 --- /dev/null +++ b/articles/enroll-byod-ios-ipados-hosts.md @@ -0,0 +1,42 @@ +# Enroll BYOD iOS/iPadOS hosts + +This guide will walk you through the process of inviting BYOD (Bring Your Own Device) iPhones and iPads to enroll in Fleet. + +By enrolling BYOD iPhones and iPads in Fleet, IT admins can manage software installations, enforce settings, and ensure devices comply with company policies. By adding BYOD devices, you can monitor, enforce settings, and manage security on BYOD iPhones and iPads in real-time, providing enhanced control without compromising user autonomy. This helps secure access to organizational resources while maintaining control over device configurations. + +## Prerequisites + +* Fleet [v4.57.0](https://github.com/fleetdm/fleet/releases/tag/fleet-v4.57.0). +* [MDM enabled and configured](https://fleetdm.com/guides/macos-mdm-setup) + +## Enrolling BYOD iPad/iOS devices in Fleet + +* **Step 1: Navigate to the manage hosts page** + * Click “Hosts” in the top navigation bar +* **Step 2: Choose the team** + * Select the desired [team](https://fleetdm.com/guides/teams) from the menu at the top of the screen +* **Step 3: Get a link to share with your end users** + * Click on “Add hosts.” + * In the modal, select the **iOS & iPadOS** tab. + * Copy the link to enroll hosts. +* **Step 4: Distribute the link** + * Share the link with your end users using an introductory email or message. + * The link provides instructions to guide users through downloading and installing Fleet’s enrollment profile. + +> Each team has a unique URL that includes the team's enrollment secret. This enrollment secret ensures that devices are assigned to the correct team during enrollment. When an incorrect enroll secret is provided, users can still download the enrollment profile, but the enrollment itself will fail (403 error). + +## Conclusion + +This guide covered how to invite and enroll BYOD iPhones and iPads into Fleet. This allows IT admins to manage software, enforce settings, and ensure compliance with organizational policies. Streamlining the enrollment process will enable you to secure access to company resources while maintaining control over end-user devices. + +For more information on device management and other features, explore Fleet’s documentation and guides to optimize your setup and keep your devices fully secure. + +See Fleet's [documentation](https://fleetdm.com/docs/using-fleet) and additional [guides](https://fleetdm.com/guides) for more details on advanced setups, software features, and vulnerability detection. + + + + + + + + diff --git a/articles/fleet-4.57.0.md b/articles/fleet-4.57.0.md new file mode 100644 index 000000000000..4c9f959f9a44 --- /dev/null +++ b/articles/fleet-4.57.0.md @@ -0,0 +1,97 @@ +# Fleet 4.57.0 | Software improvements, policy automation, GitLab support. + +![Fleet 4.57.0](../website/assets/images/articles/fleet-4.57.0-1600x900@2x.png) + +Fleet 4.57.0 is live. Check out the full [changelog](https://github.com/fleetdm/fleet/releases/tag/fleet-v4.57.0) or continue reading to get the highlights. +For upgrade instructions, see our [upgrade guide](https://fleetdm.com/docs/deploying/upgrading-fleet) in the Fleet docs. + +## Highlights +* Software improvements +* Policy automation: install software +* iPhone/iPad BYOD +* GitLab pipelines for GitOps + +### Software improvements + +Fleet allows admins to edit software items directly, offering greater control over software management across hosts. This feature allows IT teams to modify details such as software names or versions, ensuring the software inventory remains accurate and aligned with organizational needs. Additionally, Fleet has introduced the option to uninstall software from hosts, simplifying the removal of unwanted or outdated applications. + +For most cases, Fleet handles the uninstall process automatically, with the uninstall script conveniently located under “Advanced options.” However, Fleet stands out by allowing administrators to view and tweak the script if needed. This flexibility is beneficial when a host is in a unique state or the automatic uninstall process encounters issues. Fleet strives to provide full transparency into what’s under the hood, enabling IT teams to make necessary adjustments for specific scenarios. These updates enhance the efficiency of software management while maintaining flexibility, reflecting Fleet’s commitment to providing user-centric and adaptable solutions. + +### Policy automation: install software + +Admins can automatically trigger software installations when a policy fails, adding a proactive approach to maintaining compliance and security. This feature is handy when a device is found to have a vulnerable version of software installed. If a policy detects this vulnerability, Fleet can automatically install a secure, updated version of the software to remediate the issue and bring the host back into compliance. This automation helps IT teams address vulnerabilities quickly and efficiently, without manual intervention, ensuring that devices across the fleet remain secure and up-to-date. It highlights Fleet’s commitment to streamlining device management and enhancing security through automation. + +### iPhone/iPad BYOD + +Fleet now supports Bring Your Own Device (BYOD) enrollment for iPhone (iOS) and iPad (iPadOS) devices, providing organizations with a more flexible approach to managing employee-owned devices. This feature allows employees to enroll personal iPhones and iPads into Fleet’s Mobile Device Management (MDM) system, enabling IT teams to enforce security policies, manage configurations, and ensure compliance without needing complete control over the entire device. With BYOD enrollment, companies can balance security and privacy, seamlessly managing work-related configurations on personal devices while respecting the end user’s control over their personal data. This update enhances Fleet’s capabilities for managing various devices and supports organizations with modern, flexible workforce environments. + +### GitLab pipelines for GitOps + +Fleet now supports GitLab pipelines for its [GitOps integration](https://github.com/fleetdm/fleet-gitops), expanding the flexibility of how organizations manage their device configurations and policies through version control. With GitLab pipelines, IT teams can automate the deployment and management of Fleet configurations directly from their GitLab repositories, streamlining workflows and ensuring that changes are tracked, tested, and deployed consistently across their fleet. This integration enhances the automation and reliability of device management, enabling teams to adopt a more scalable and auditable approach to managing their Fleet environment. By supporting both GitLab and existing CI/CD tools, Fleet continues to empower organizations to implement modern, efficient workflows for managing configurations and policies. + +## Changes + +**NOTE:** Beginning with Fleet v4.55.0, Fleet no longer supports MySQL 5.7 because it has reached [end of life](https://mattermost.com/blog/mysql-5-7-reached-eol-upgrade-to-mysql-8-x-today/#:~:text=In%20October%202023%2C%20MySQL%205.7,to%20upgrade%20to%20MySQL%208.). The minimum version supported is MySQL 8.0.36. + +**Endpoint Operations** + +- Added support for configuring policy installers via GitOps. +- Added support for policies in "No team" that run on hosts that belong to "No team". +- Added reserved team names: "All teams" and "No team". +- Added support the software status filter for 'No teams' on the hosts page. +- Enable 'No teams' funcitonality for the policies page and associated workflows. +- Added reset install counts and cancel pending installs/uninstalls when GitOps installer updates change package contents. +- Added support for software installer packages, self-service flag, scripts, pre-install query, and self-service availability to be edited in-place rather than deleted and re-added. + +**Device Management (MDM)** + +- Added feature allowing automatic installation of software on hosts that fail policies. +- Added feature for end users to enroll BYOD devices into Fleet MDM. +- Added the ability to use Fleet to uninstall packages from hosts. +- Added an endpoint for getting an OTA MDM profile for enrolling iOS and iPadOS hosts. +- Added protocol support for OTA enrollment and automatic team assignment for hosts. +- Added validation of Setup Assistant profiles on profile upload. +- Added validation to prevent installing software on a host with a pending installation. +- Allowed custom SCEP CA certificates with any kind of extendedKeyUsage attributes. +- Modified `POST /api/latest/fleet/software/batch` endpoint to be asynchronous and added a new endpoint `GET /api/latest/fleet/software/batch/{request_uuid}` to retrieve the result of the batch upload. + +**Vulnerability Management** + +- Fixed a false negative vulnerability for git. +- Fixed false positive vulnerabilities for minio. +- Fixed an issue where virtual box for macOS wasn't matching against the NVD product name. +- Fixed Ubuntu python package false positive vulnerabilities by removing duplicate entries for ubuntu python packages installed by dpkg and renaming remaining pip installed packages to match OVAL definitions. + +**Bug fixes and improvements** + +- Updated Go to go1.23.1. +- Removed validation of APNS certificate from server startup. +- Removed invalid node keys from server logs. +- Improved the UX of turning off MDM on an offline host. +- Improved clarity of GitOps VPP app ID type errors. +- Improved gitops error message about enabling windows MDM. +- Improved messaging for VPP token constraint errors. +- Improved loading state for UI tables when no data is present yet. +- Improved permissions so that hosts can no longer access installers that aren't directly assigned to them. +- Improved verification of premium license before uploading VPP tokens. +- Added "0 items" description on empty software tables for UI consistency. +- Updated the macos target minimum version tooltip. +- Fixed logic to properly catch and log APNs errors. +- Fixed UI overflow issues with OS settings table data. +- Fixed regression for checking email used to get a signed CSR. +- Fixed bugs on enrollment profiles when the organization name contains invalid XML characters. +- Fixed an issue with cron profiles delivery failing if a Windows VM is enrolled twice. +- Fixed issue where Fleet server could start when an expired ABM certificate was provided as server config. +- Fixed self-service checkbox appearing when iOS or iPadOS app is selected. + + +## Ready to upgrade? + +Visit our [Upgrade guide](https://fleetdm.com/docs/deploying/upgrading-fleet) in the Fleet docs for instructions on updating to Fleet 4.57.0. + + + + + + + diff --git a/docs/Contributing/API-for-contributors.md b/docs/Contributing/API-for-contributors.md index 0b830dbc0719..2ba361b2c3a7 100644 --- a/docs/Contributing/API-for-contributors.md +++ b/docs/Contributing/API-for-contributors.md @@ -3325,92 +3325,7 @@ If both `team_id` and `team_name` parameters are included, this endpoint will re `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`. Ommitting these parameters will add software to 'No Team'. | -| 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`. Ommitting these parameters will add software to 'No Team'. | -| dry_run | bool | query | If `true`, will validate the provided software packages and return any validation errors, but will not apply the changes. | -| software | object | body | The team's software that will be available for install. | -| software.packages | list | body | An array of 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, `post_install_script` - script that runs after software install, and `uninstall_script` - command that Fleet runs to uninstall software. | -| software.app_store_apps | list | body | An array objects. Each object consists of `app_store_id` - ID of the App Store app. | - -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: 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" - } - ] -} -``` - -### Batch-apply VPP apps - -_Available in Fleet Premium._ - -`POST /api/latest/fleet/software/app_store_apps/batch` - -#### Parameters - -| Name | Type | In | Description | -| --------- | ------ | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| team_name | string | query | The name of the team to add the software package to. Ommitting this parameter will add software to 'No Team'. | -| dry_run | bool | query | If `true`, will validate the provided VPP apps and return any validation errors, but will not apply the changes. | -| app_store_apps | list | body | An array of objects. Each object contains `app_store_id` and `self_service`. | -| app_store_apps.app_store_id | string | body | ID of the App Store app. | -| app_store_apps.self_service | boolean | body | Whether the VPP app is "Self-service" or not. | - -#### Example - -`POST /api/latest/fleet/software/app_store_apps/batch` -```json -{ - "team_name": "Foobar", - "app_store_apps": { - { - "app_store_id": "597799333", - "self_service": false, - }, - { - "app_store_id": "497799835", - "self_service": true, - } - } -} -``` - -##### Default response - -`Status: 204` - - ### Run live script +### Run live script Run a live script and get results back (5 minute timeout). Live scripts only runs on the host if it has no other scripts running. @@ -3449,130 +3364,3 @@ Run a live script and get results back (5 minute timeout). Live scripts only run "exit_code": 0 } ``` - -### Get token to download package - -_Available in Fleet Premium._ - -`POST /api/v1/fleet/software/titles/:software_title_id/package/token?alt=media` - -The returned token is a one-time use token that expires after 10 minutes. - -#### Parameters - -| Name | Type | In | Description | -|-------------------|---------|-------|------------------------------------------------------------------| -| software_title_id | integer | path | **Required**. The ID of the software title for software package. | -| team_id | integer | query | **Required**. The team ID containing the software package. | -| alt | integer | query | **Required**. Must be specified and set to "media". | - -#### Example - -`POST /api/v1/fleet/software/titles/123/package/token?alt=media&team_id=2` - -##### Default response - -`Status: 200` - -```json -{ - "token": "e905e33e-07fe-4f82-889c-4848ed7eecb7" -} -``` - -### Download package using a token - -_Available in Fleet Premium._ - -`GET /api/v1/fleet/software/titles/:software_title_id/package/token/:token?alt=media` - -#### Parameters - -| Name | Type | In | Description | -|-------------------|---------|------|--------------------------------------------------------------------------| -| software_title_id | integer | path | **Required**. The ID of the software title to download software package. | -| token | string | path | **Required**. The token to download the software package. | - -#### Example - -`GET /api/v1/fleet/software/titles/123/package/token/e905e33e-07fe-4f82-889c-4848ed7eecb7` - -##### Default response - -`Status: 200` - -```http -Status: 200 -Content-Type: application/octet-stream -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 d7b8b8f172da..638728015b9d 100644 --- a/docs/REST API/rest-api.md +++ b/docs/REST API/rest-api.md @@ -8651,6 +8651,10 @@ Deletes the session specified by ID. When the user associated with the session n - [Get package install result](#get-package-install-result) - [Download package](#download-package) - [Delete package or App Store app](#delete-package-or-app-store-app) +- [Batch-apply software](#batch-apply-software) +- [Batch-apply app store apps](#batch-apply-app-store-apps) +- [Get token to download package](#get-token-to-download-package) +- [Download package using a token](#download-package-using-a-token) ### List software @@ -9535,6 +9539,117 @@ Deletes software that's available for install (package or App Store app). `Status: 204` +### 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`. Omitting these parameters will add software to "No Team". | +| 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`. Omitting these parameters will add software to "No Team". | +| dry_run | bool | query | If `true`, will validate the provided software packages and return any validation errors, but will not apply the changes. | +| software | object | body | The team's software that will be available for install. | +| software.packages | list | body | An array of 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, `post_install_script` - script that runs after software install, and `uninstall_script` - command that Fleet runs to uninstall software. | +| software.app_store_apps | list | body | An array objects. Each object consists of `app_store_id` - ID of the App Store app. | + +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` + +### Batch-apply app store apps + +_Available in Fleet Premium._ + +`POST /api/v1/fleet/software/app_store_apps/batch` + +#### Parameters + +| Name | Type | In | Description | +|-----------------|---------|-------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| team_name | integer | query | **Required**. The name of the team to add the app to. | +| dry_run | bool | query | If `true`, will validate the provided apps and return any validation errors, but will not apply the changes. | +| apps_store_apps | list | body | The list of objects containing `app_store_id`: a string representation of the app's App ID, `self_service`: a bool indicating if the app's installation can be initiated by end users. | + +> Note that this endpoint replaces all apps associated with a team. + +#### Example + +`POST /api/v1/fleet/software/app_store_apps/batch` + +#### Default response + +`Status: 204` + +### Get token to download package + +_Available in Fleet Premium._ + +`POST /api/v1/fleet/software/titles/:software_title_id/package/token?alt=media` + +The returned token is a one-time use token that expires after 10 minutes. + +#### Parameters + +| Name | Type | In | Description | +|-------------------|---------|-------|------------------------------------------------------------------| +| software_title_id | integer | path | **Required**. The ID of the software title for software package. | +| team_id | integer | query | **Required**. The team ID containing the software package. | +| alt | integer | query | **Required**. Must be specified and set to "media". | + +#### Example + +`POST /api/v1/fleet/software/titles/123/package/token?alt=media&team_id=2` + +##### Default response + +`Status: 200` + +```json +{ + "token": "e905e33e-07fe-4f82-889c-4848ed7eecb7" +} +``` + +### Download package using a token + +_Available in Fleet Premium._ + +`GET /api/v1/fleet/software/titles/:software_title_id/package/token/:token?alt=media` + +#### Parameters + +| Name | Type | In | Description | +|-------------------|---------|------|--------------------------------------------------------------------------| +| software_title_id | integer | path | **Required**. The ID of the software title to download software package. | +| token | string | path | **Required**. The token to download the software package. | + +#### Example + +`GET /api/v1/fleet/software/titles/123/package/token/e905e33e-07fe-4f82-889c-4848ed7eecb7` + +##### Default response + +`Status: 200` + +```http +Status: 200 +Content-Type: application/octet-stream +Content-Disposition: attachment +Content-Length: +Body: +``` + + ## Vulnerabilities - [List vulnerabilities](#list-vulnerabilities) diff --git a/website/assets/images/articles/fleet-4.57.0-1600x900@2x.png b/website/assets/images/articles/fleet-4.57.0-1600x900@2x.png new file mode 100644 index 000000000000..ec48ddd12ae9 Binary files /dev/null and b/website/assets/images/articles/fleet-4.57.0-1600x900@2x.png differ diff --git a/website/config/routes.js b/website/config/routes.js index ffd37f34396f..1d6188090a35 100644 --- a/website/config/routes.js +++ b/website/config/routes.js @@ -324,6 +324,7 @@ module.exports.routes = { 'GET /use-cases/get-and-stay-compliant-across-your-devices-with-fleet': '/securing/get-and-stay-compliant-across-your-devices-with-fleet', 'GET /use-cases/import-and-export-queries-and-packs-in-fleet': '/guides/import-and-export-queries-and-packs-in-fleet', 'GET /guides/import-and-export-queries-and-packs-in-fleet': '/guides/import-and-export-queries-in-fleet', + 'GET /guides/deploy-security-agents': '/guides/deploy-software-packages', 'GET /use-cases/locate-assets-with-osquery': '/guides/locate-assets-with-osquery', 'GET /use-cases/osquery-a-tool-to-easily-ask-questions-about-operating-systems': '/guides/osquery-a-tool-to-easily-ask-questions-about-operating-systems', 'GET /use-cases/osquery-consider-joining-against-the-users-table': '/guides/osquery-consider-joining-against-the-users-table', @@ -565,6 +566,10 @@ module.exports.routes = { 'GET /learn-more-about/apple-business-manager-gitops': '/docs/using-fleet/gitops#apple-business-manager', 'GET /learn-more-about/s3-bootstrap-package': '/docs/configuration/fleet-server-configuration#s-3-software-installers-bucket', 'GET /learn-more-about/policy-automation-install-software': '/guides/automatic-software-install-in-fleet', + 'GET /learn-more-about/exe-install-scripts': '/guides/exe-install-scripts', + 'GET /learn-more-about/install-scripts': '/guides/deploy-software-packages#install-script', + 'GET /learn-more-about/uninstall-scripts': '/guides/deploy-software-packages#uninstall-script', + 'GET /learn-more-about/read-package-version': '/guides/deploy-software-packages##add-a-software-package-to-a-team', // Sitemap // =============================================================================================================