fleetdm · rachaelshaw · Sep 17, 2024 · Sep 17, 2024 · Sep 17, 2024 · Sep 17, 2024
diff --git a/.github/ISSUE_TEMPLATE/story.md b/.github/ISSUE_TEMPLATE/story.md
@@ -32,15 +32,15 @@ What else should contributors [keep in mind](https://fleetdm.com/handbook/compan
 ## Changes
 
 ### Product
-- [ ] Reference documentation changes: TODO <!-- Specify references documentation changes at fleetdm.com/docs -->
 - [ ] UI changes: TODO <!-- Insert the link to the relevant Figma cover page. Put "No changes" if there are no changes to the user interface. -->
 - [ ] CLI (fleetctl) usage changes: TODO <!-- Insert the link to the relevant Figma cover page. Put "No changes" if there are no changes to the CLI. -->
-- [ ] YAML changes: TODO <!-- Specify changes as a PR to the YAML files doc page. Put "No changes" if there are no changes necessary. -->
-- [ ] REST API changes: TODO <!-- Specify changes as a PR to the REST API doc page. Put "No changes" if there are no changes necessary. Move this item to the engineering list below if engineering will design the API changes. -->
+- [ ] YAML changes: TODO <!-- Specify changes in the YAML files doc page as a PR to the reference docs release branch. Put "No changes" if there are no changes necessary. -->
+- [ ] REST API changes: TODO <!-- Specify changes in the the REST API doc page as a PR to reference docs release branch. Put "No changes" if there are no changes necessary. Move this item to the engineering list below if engineering will design the API changes. -->
 - [ ] Fleet's agent (fleetd) changes: TODO <!-- Specify changes to fleetd. If the change requires a new Fleet (server) version, consider specifying to only enable this change in new Fleet versions. Put "No changes" if there are no changes necessary. -->
 - [ ] Activity changes: TODO <!-- Specify changes to Fleet's activity feed as a draft PR to the Audit log page in the contributor docs: https://github.com/fleetdm/fleet/blob/main/docs/Contributing/Audit-logs.md This PR will be closed before release because the Audit log page is automatically generated: https://fleetdm.com/handbook/company/communications#audit-logs Put "No changes" if there are no changes necessary. -->
-- [ ] Permissions changes: TODO <!-- Specify changes as a PR to the Manage access doc page. If doc changes aren't necessary, explicitly mention no changes to the doc page. Put "No changes" if there are no permissions changes. -->
-- [ ] Changes to paid features or tiers: TODO  <!-- Specify changes as a PR to fleetdm.com/pricing (pricing-features-table.yml). Remove this checkbox and specify "Fleet Free" or "Fleet Premium" if there are no changes to the pricing page necessary. -->
+- [ ] Permissions changes: TODO <!-- Specify changes in the Manage access doc page as a PR to the reference docs release branch. If doc changes aren't necessary, explicitly mention no changes to the doc page. Put "No changes" if there are no permissions changes. -->
+- [ ] Changes to paid features or tiers: TODO  <!-- Specify changes in pricing-features-table.yml as a PR to reference docs release branch. Remove this checkbox and specify "Fleet Free" or "Fleet Premium" if there are no changes to the pricing page necessary. -->
+- [ ] Other reference documentation changes: TODO <!-- Any other reference doc changes? Specify changes as a PR to reference docs release branch. Put "No changes" if there are no changes necessary. -->
 - [ ] Once shipped, requester has been notified
 
 ### Engineering

@@ -13,18 +13,13 @@ on:
       - '.github/workflows/generate-desktop-targets.yml'
   workflow_dispatch:
 
-# This allows a subsequently queued workflow run to interrupt previous runs
-concurrency:
-  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id}}
-  cancel-in-progress: true
-
 defaults:
   run:
     # fail-fast using bash -eo pipefail. See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#exit-codes-and-error-action-preference
     shell: bash
 
 env:
-  FLEET_DESKTOP_VERSION: 1.32.0
+  FLEET_DESKTOP_VERSION: 1.33.0
 
 permissions:
   contents: read

@@ -5,11 +5,6 @@ on:
     tags:
       - "orbit-*" # For testing, use a pre-release tag like 'orbit-1.24.0-1'
 
-# This allows a subsequently queued workflow run to interrupt previous runs
-concurrency:
-  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id}}
-  cancel-in-progress: true
-
 defaults:
   run:
     # fail-fast using bash -eo pipefail. See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#exit-codes-and-error-action-preference

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,3 +1,56 @@
+## Fleet 4.57.0 (Sep 23, 2024)
+
+**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.
+
 ## Fleet 4.56.0 (Sep 7, 2024)
 
 ### Endpoint operations

diff --git a/CODEOWNERS b/CODEOWNERS
@@ -66,8 +66,8 @@ go.mod @fleetdm/go
 #
 # (see website/config/custom.js for DRIs of other paths not listed here)
 ##############################################################################################
-/docs                                           @rachaelshaw
-/docs/REST\ API/rest-api.md                     @rachaelshaw # « REST API reference documentation
+/docs                                           @rachaelshaw @lukeheath
+/docs/REST\ API/rest-api.md                     @rachaelshaw @lukeheath # « REST API reference documentation
 /docs/Contributing/API-for-contributors.md      @lukeheath # « Advanced / contributors-only API reference documentation
 /schema                                         @eashaw # « Data tables (osquery/fleetd schema) documentation
 /docs/Deploy/_kubernetes/ @dherder # « Kubernetes best practice

diff --git a/Makefile b/Makefile
@@ -74,6 +74,7 @@ define HELP_TEXT
 	make generate-go  - Generate and bundle required go code
 	make generate-js  - Generate and bundle required js code
 	make generate-dev - Generate and bundle required code in a watch loop
+	make generate-doc - Generate updated API documentation for activities, osquery flags
 
     make clean        - Clean all build artifacts
 	make clean-assets - Clean assets only

diff --git a/articles/automatic-software-install-in-fleet.md b/articles/automatic-software-install-in-fleet.md
@@ -0,0 +1,80 @@
+# Automatic policy-based installation of software on hosts
+
+![Top Image](../website/assets/images/articles/automatic-software-install-top-image.png)
+
+Fleet [v4.57.0](https://github.com/fleetdm/fleet/releases/tag/fleet-v4.57.0) introduces the ability to automatically and remotely install software on hosts based on predefined policy failures. This guide will walk you through the process of configuring fleet for automatic installation of software on hosts using uploaded installation images and based on programmed policies.  You'll learn how to configure and use this feature, as well as understand how the underlying mechanism works.
+
+Fleet allows its users to upload trusted software installation files to be installed and used on hosts. This installation could be conditioned on a failure of a specific Fleet Policy.
+
+## Prerequisites
+
+* Fleet premium with Admin permissions.
+* Fleet [v4.57.0](https://github.com/fleetdm/fleet/releases/tag/fleet-v4.57.0) or greater.
+
+## Step-by-step instructions
+
+1. **Adding software**: Add any software to be available for installation. Follow the [deploying software](https://fleetdm.com/guides/deploy-security-agents) document with instructions how to do it. Note that all installation steps (pre-install query, install script, and post-install script) will be executed as configured, regardless of the policy that triggers the installation.
+
+
+![Add software](../website/assets/images/articles/automatic-software-install-add-software.png)
+
+Current supported software deployment formats:
+- macOS: .pkg
+- Windows: .msi, .exe
+- Linux: .deb
+
+Coming soon:
+- VPP for iOS and iPadOS
+
+2. **Add a policy**: In Fleet, add a policy that failure to pass will trigger the required installation. Go to Policies tab --> Press the top right "Add policy" button. --> Click "create your own policy" --> Enter your policy SQL --> Save --> Fill in details in the Save modal and Save.
+
+```
+SELECT 1 FROM apps WHERE name = 'Adobe Acrobat Reader.app' AND version_compare(bundle_short_version, '23.001.20687') >= 0;
+```
+
+Note: In order to know the exact application name to put in the query (e.g. "Adobe Acrobat Reader.app" in the query above) you can manually install it on a canary/test host and then query SELECT * from apps;
+
+
+3. **Manage automation**: Open Manage Automations: Policies Tab --> top right "Manage automations" --> "Install software".
+
+![Manage policies](../website/assets/images/articles/automatic-software-install-policies-manage.png)
+
+4. **Select policy**: Select (click the check box of) your newly created policy. To the right of it select from the
+   drop-down list the software you would like to be installed upon failure of this policy.
+
+![Install software modal](../website/assets/images/articles/automatic-software-install-install-software.png)
+
+Upon failure of the selected policy, the selected software installation will be triggered.
+
+## How does it work?
+
+* After configuring Fleet to auto-install a specific software the rest will be done automatically.
+* The policy check mechanism runs on a typical 1 hour cadence on all online hosts. 
+* Fleet will send install requests to the hosts on the first policy failure (first "No" result for the host) or if a policy goes from "Yes" to "No". On this iteration it will not send a install request if a policy is already failing and continues to fail ("No" -> "No"). See the following flowchart for details.
+
+![Flowchart](../website/assets/images/articles/automatic-software-install-workflow.png)
+*Detailed flowchart*
+
+## Using the REST API for self-service software packages
+
+Fleet provides a REST API for managing software packages, including self-service software packages.  Learn more about Fleet's [REST API](https://fleetdm.com/docs/rest-api/rest-api#add-team-policy).
+
+## Managing self-service software packages with GitOps
+
+To manage self-service software packages using Fleet's best practice GitOps, check out the `software` key in the [GitOps reference documentation](https://fleetdm.com/docs/configuration/yaml-files#policies).
+
+## Conclusion
+
+Software deployment can be time-consuming and risky. This guide presents Fleet's ability to mass deploy software to your fleet in a simple and safe way. Starting with uploading a trusted installer and ending with deploying it to the proper set of machines answering the exact policy defined by you.
+
+Leveraging Fleet’s ability to install and upgrade software on your hosts, you can streamline the process of controlling your hosts, replacing old versions of software and having the up-to-date info on what's installed on your fleet.
+
+By automating software deployment, you can gain greater control over what's installed on your machines and have better oversight of version upgrades, ensuring old software with known issues is replaced.
+
+<meta name="articleTitle" value="Automatic installation of software on hosts">
+<meta name="authorFullName" value="Sharon Katz">
+<meta name="authorGitHubUsername" value="sharon-fdm">
+<meta name="category" value="guides">
+<meta name="publishedOn" value="2024-09-23">
+<meta name="articleImageUrl" value="../website/assets/images/articles/automatic-software-install-in-fleet-731x738@2x.png">
+<meta name="description" value="A guide to workflows using automatic software installation in Fleet.">