Elgato_dark/fleet
1
0
Fork 0
mirror of https://github.com/fleetdm/fleet synced 2026-05-22 00:18:27 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 139

Merge branch 'main' into feature_19010-ipad-ios-lock-wipe

Browse source
This commit is contained in:
George Karr 2024-06-13 14:01:02 -05:00 committed by GitHub
commit 4e2f7e53c3
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
320 changed files with 5678 additions and 1703 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
.github/ISSUE_TEMPLATE/release-qa.md vendored
View file

@ -99,6 +99,14 @@ Smoke tests are limited to core functionality and serve as a pre-release final r
3. Verify able to run MDM commands on both macOS and Windows hosts from the CLI.
</td><td>pass/fail</td></tr>
<tr><td>MDM migration flow</td><td>Verify MDM migration for ADE and non-ADE hosts</td><td>
1. Turn off MDM on an ADE-eligible macOS host and verify that the native, "Device Enrollment" macOS notification appears.
2. On the My device page, follow the "Turn on MDM" instructions and verify that MDM is turned on.
3. Turn off MDM on a non ADE-eligible macOS host.
4. On the My device page, follow the "Turn on MDM" instructions and verify that MDM is turned on.
</td><td>pass/fail</td></tr>
<tr><td>Scripts</td><td>Verify script library and execution</td><td>
1. Verify able to run a script on all host types from CLI.

1
.github/workflows/dogfood-deploy.yml vendored
View file

@ -31,6 +31,7 @@ env:
TF_VAR_elastic_url: ${{ secrets.ELASTIC_APM_SERVER_URL }}
TF_VAR_elastic_token: ${{ secrets.ELASTIC_APM_SECRET_TOKEN }}
TF_VAR_geolite2_license: ${{ secrets.MAXMIND_LICENSE }}
TF_VAR_dogfood_sidecar_enroll_secret: ${{ secrets.DOGFOOD_SERVERS_CANARY_ENROLL_SECRET }}
permissions:
id-token: write

2
.github/workflows/generate-desktop-targets.yml vendored
View file

@ -24,7 +24,7 @@ defaults:
shell: bash
env:
FLEET_DESKTOP_VERSION: 1.25.0
FLEET_DESKTOP_VERSION: 1.26.0
permissions:
contents: read

50
CHANGELOG.md
View file

@ -1,3 +1,53 @@
## Fleet 4.51.1 (Jun 12, 2024)
### Bug fixes
* Added S3 config variables with a `carves` and `software_installers` prefix, which were used to configure buckets for those features. The existing non-prefixed variables were kept for backwards compatibility.
* Fixed a bug that prevented unused script contents to be periodically cleaned up from the database.
## Fleet 4.51.0 (Jun 10, 2024)
### Endpoint Operations
- Added support for environment variables in configuration profiles for GitOps.
- `fleetctl gitops --dry-run` now errors on duplicate (or conflicting) global/team enroll secrets.
- Added `activities_webhook` configuration option to allow for a webhook to be called when an activity is recorded. This can be used to send activity data to external services. If the webhook response is a 429 error code, the webhook retries for up to 30 minutes.
- Added Tuxedo OS to the Linux distribution platform list.
### Device Management (MDM)
- **NOTE:** Added new required Fleet server config environment variable when MDM is enabled,
`FLEET_SERVER_PRIVATE_KEY`. This variable contains the private key used to encrypt the MDM
certificates and keys stored in Fleet. Learm more at
https://fleetdm.com/learn-more-about/fleet-server-private-key.
- Added MDM support for iPhone/iPad.
- Added software self-service support.
- Added query parameter `self_service` to filter the list of software titles and the list of a host's software so that only those available to install via self-service are returned.
- Added the device-authenticated endpoint `POST /device/{token}/software/install/{software_title_id}` to self-install software.
- Added new endpoints to configure ABM keypairs and tokens.
- Added `GET /fleet/mdm/apple/request_csr` endpoint, which returns the signed APNS CSR needed to activate Apple MDM.
- Added the ability to automatically log off and lock out `Administrator` users on Windows hosts.
- Added clearer error messages when attempting to set up Apple MDM without a server private key configured.
- Added UI for the global and host activities for self-service software installation.
- Updated UI to support new workflows for macOS MDM setup and credentials.
- Updated UI to support software self-service features.
- Updated UI controls page language and hid CTA button for users without access to turn on MDM.
### Vulnerability Management
- Updated the CIS policies for Windows 11 Enterprise from v2.0.0 (03-07-2023) to v3.0.0 (02-22-2024).
- Fleet now detects Ubuntu kernel vulnerabilities from the Canonical OVAL feed.
- Fleet now detects and reports vulnerabilities on Firefox ESR editions on macOS.
### Bug fixes and improvements
- Fixed a bug that might prevent enqueuing commands to renew SCEP certificates if the host was enrolled more than once.
- Prevented the `host_id`s field from being returned from the list labels endpoint.
- Improved software ingestion performance by deduplicating incoming software.
- Placed all form field label tooltips on top.
- Fixed a number of related issues with the filtering and sorting of the queries table.
- Added various optimizations to the rendering of the queries table.
- Fixed host query page styling bugs.
- Fixed a UI bug where "Wipe" action was not being hidden from observers.
- Fixed UI bug for builtin label names for selecting targets.
- Removed references to Administrator accounts in the comments of the Windows lock script.
## Fleet 4.50.2 (May 31, 2024)
### Bug fixes

6
CODEOWNERS
View file

@ -64,9 +64,9 @@ go.mod @fleetdm/go
#
# (see website/config/custom.js for DRIs of other paths not listed here)
##############################################################################################
/docs @rachaelshaw
/docs/Using-Fleet/REST-API.md @rachaelshaw # « REST API reference documentation
/docs/Contributing/API-for-contributors.md @rachaelshaw # « Advanced / contributors-only API reference documentation
/docs @rachaelshaw @lukeheath
/docs/Using-Fleet/REST-API.md @rachaelshaw @lukeheath # « REST API reference documentation
/docs/Contributing/API-for-contributors.md @rachaelshaw @lukeheath # « Advanced / contributors-only API reference documentation
/schema @eashaw # « Data tables (osquery/fleetd schema) documentation
/docs/Deploy/_kubernetes/ @dherder # « Kubernetes best practice
##############################################################################################

346
articles/deploy-fleet-on-ubuntu-with-elastic.md Normal file
View file

@ -0,0 +1,346 @@
# Deploy Fleet on Ubuntu with Elastic
![Deploy Fleet on Ubuntu with Elastic](../website/assets/images/articles/deploy-fleet-on-ubuntu-with-elastic-1600x900@2x.png)
[<img src="../website/assets/images/articles/deploy-fleet-on-ubuntu-with-elastic-internews_logo-256x237@2x.png" width="128" align="right"/>](https://internews.org/)_Today we wanted to feature [Josh](https://defensivedepth.com/), a member of our community. His work was sponsored by [Internews](https://internews.org/). If you are interested in contributing to the Fleet blog, feel free to [contact us](https://fleetdm.com/company/contact) or reach out to [@jdstrong](https://osquery.slack.com/team/U04MTPBAHQS) on the osquery slack._
This guide provides a detailed walkthrough for setting up a small production environment of Fleet alongside Elastic components (Elasticsearch, Kibana, Filebeat). The setup integrates Filebeat to collect scheduled query results from Fleet and feed them into Elasticsearch, while Kibana will be utilized for data visualization and the creation of detections. Additionally, Nginx will serve as a reverse proxy for the Kibana and Fleet web interfaces and will segregate the web administration and agent data+control planes of Fleet for more fine-grained access control.
The installation and configuration will begin with the Elastic stack components, followed by Fleet and its dependencies. For this guide, they will all be installed on a single server; however, for larger deployments or requirements of higher availability and scalability, a more distributed approach across multiple servers and geographical regions is recommended.
### Network, server & DNS setup
This guide is based on Ubuntu 22.04 LTS, although the installation procedures for the components remain consistent across newer versions of the operating system.
For this guide, subdomain `fleet.localhost.invalid` is pointed to the server's public IP. Replace this subdomain with a valid one configured as such.
Ports needed, inbound to server:
- `TCP/80` (Only used for the initial Let's Encrypt setup)
- `TCP/443` (Used initially for the Let's Encrypt setup, and then longterm for Fleet distributed agents to checking for data and control)
- `TCP/8443` (Used for Kibana web interface)
- `TCP/9443` (Used for Fleet web interface)
Set up access control where it makes sense - perimeter firewall or on the server itself. Set the ports for the Kibana (`TCP/8443`) and Fleet (`TCP/9443`) web interfaces to only be accessible from a known-trusted IP space. Also set rules for `TCP/443`, which is used for the deployed osquery agents to check in with Fleet. A common configuration is for the web interface ports to be accessible to a single IP or small set of IPs, and for the osquery check in port to be accessible anywhere.
Be aware that if you are using a proxy like Cloudflare, you will need to confirm that the ports in this guide will work as expected.
### Update OS
Let's start by updating the system's packages and creating a workspace directory:
```sh
sudo apt-get update && sudo apt-get dist-upgrade -y
mkdir workspace && cd workspace
```
### Install & configure Certbot
Next up is to install Certbot to create and manage our free Let's Encrypt SSL certificate. This certificate will be used by for all components.
```sh
sudo apt-get install certbot -y
sudo certbot certonly --standalone
```
Select option 1 to spin up a temporary web server. Enter the domain that you have pointed to your public IP. You will need TCP/80 & TCP/443 open to the server.
By default, the certificate and key are saved at:
- Certificate: `/etc/letsencrypt/live/fleet.localhost.invalid/fullchain.pem`
- Key: `/etc/letsencrypt/live/fleet.localhost.invalid/privkey.pem`
### Install & configure Nginx
Let's install Nginx and configure it as a reverse proxy for Fleet and Kibana.
```sh
sudo apt-get install nginx
nano /etc/nginx/sites-available/fleet # use the below config, remember to update the path to the certificate files
sudo ln -s /etc/nginx/sites-available/fleet /etc/nginx/sites-enabled/ # symlink the config file to enable it
nginx -t # Test the config to make sure there are no syntax errors
sudo systemctl reload nginx # Reload nginx to make the config active
sudo systemctl status nginx # Check the reload to confirm that there are no errors
```
Nginx Config file:
```sh
# Define SSL configuration
ssl_certificate /etc/letsencrypt/live/fleet.localhost.invalid/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/fleet.localhost.invalid/privkey.pem;
# Common proxy settings
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
# Server block for Kibana on port 8443
server {
listen 8443 ssl default_server;
location / {
proxy_pass http://localhost:5601;
}
}
# Server block for Fleet on port 9443 with WebSocket support
server {
listen 9443 ssl;
add_header Content-Security-Policy "default-src 'self' 'unsafe-inline' 'unsafe-eval' https: data: blob: wss:; frame-ancestors 'self'";
location / {
proxy_pass https://localhost:4443/;
proxy_read_timeout 300;
proxy_connect_timeout 300;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "Upgrade";
}
}
# Server block for specific Orbit osquery paths on port 443
server {
listen 443 ssl;
location ~* ^/api/(osquery|fleet/orbit/(config|ping)|v1/osquery) {
proxy_pass https://localhost:4443;
}
}
```
### Install & configure Elasticsearch
In case the below does not work, consult Debian package installation instructions at https://www.elastic.co/guide/en/elasticsearch/reference/current/deb.html
Let's download and install Elasticsearch via an Ubuntu package.
One-time prep needed to add the Elastic APT repository:
```sh
wget -qO - https://artifacts.elastic.co/GPG-KEY-elasticsearch | sudo apt-key add -
echo "deb https://artifacts.elastic.co/packages/8.x/apt stable main" | sudo tee -a /etc/apt/sources.list.d/elastic-8.x.list
sudo apt-get update
```
Install the Elasticsearch package (this will install the latest stable version):
```sh
sudo apt-get install elasticsearch
```
The post-install message will contain a password generated for the Elasticsearch built-in superuser (`elastic`). Make note of it as we will need it later.
Enable and start the Elasticsearch service:
```sh
sudo systemctl daemon-reload
sudo systemctl enable --now elasticsearch.service
```
## Install & configure Kibana
Onto Kibana. Let's download, install and do the initial configuration.
```sh
sudo apt-get install kibana
```
Before we start Kibana, we need to edit the configuration file:
```sh
nano /etc/kibana/kibana.yml
```
Set the server host and public base URL by uncommenting and editing the below lines:
```yaml
server.host: "0.0.0.0" # Sets Kibana to listen on all interfaces
server.publicBaseUrl: "https://fleetmd.localhost.invalid:8443" # This should be set to your custom subdomain/port
```
Enable and start the Kibana service:
```sh
sudo /bin/systemctl daemon-reload
sudo /bin/systemctl enable --now kibana.service
```
### Initial configuration
Access Kibana at `https://fleet.localhost.invalid:8443`. If you get stuck at this step, you may not have opened ports 8443 and 9443, as needed in this walkthrough. Generate and enter the initial setup token and the verification code:
```sh
/usr/share/elasticsearch/bin/elasticsearch-create-enrollment-token -s kibana
/usr/share/kibana/bin/kibana-verification-code
```
From there, log in with the username `elastic` and the password that was generated previously, and choose `Explore on my own`. Navigate to `Management` -> `Stack Monitoring` and set up self-monitoring with `set up with self monitoring` and `Turn on monitoring`. This will give you a nice overview of Elasticsearch, Kibana and eventually Filebeat.
## Install & configure Filebeat
The final Elastic component to install is Filebeat. Let's download and configure it to pick up our osquery logs.
```sh
sudo apt-get install filebeat
```
Edit the Filebeat configuration to set up where to send its logs (Elasticsearch). We disable ssl.verification because the connection from Filebeat to Elasticsearch is local (from Filebeat on the server to Elasticsearch on the same system).
Filebeat has built-in support for osquery logs. Let's configure and then enable that filebeat module and then start the Filebeat service:
```sh
sudo nano /etc/filebeat/modules.d/osquery.yml.disabled # Use the following config
```
```yaml
# Module: osquery
- module: osquery
result:
enabled: true
# Set custom paths for the log files. If left empty,
# Filebeat will choose the paths depending on your OS.
var.paths: ["/tmp/osquery_result"]
# If true, all fields created by this module are prefixed with
# `osquery.result`. Set to false to copy the fields in the root
# of the document. The default is true.
#var.use_namespace: true
```
```sh
sudo filebeat modules enable osquery # Enable the Filebeat osquery module
sudo /bin/systemctl daemon-reload
sudo /bin/systemctl enable --now filebeat.service
```
## Install & configure MySQL
With the Elastic components installed, we can move on to Fleet. First up is installing MySQL and creating the Fleet user and database.
```sh
sudo apt-get install mysql-server -y
mysql -uroot
create database fleet; # This is the database that will be used by Fleet
create user fleet@'localhost' identified by 'FleetDMPW!'; # Create the mysql user for the Fleet database and set a strong password.
grant all privileges on fleet.* to fleet@'localhost'; # Grant the new user the necessary privileges to the Fleet database.
exit
```
## Install & configure Redis
Redis is used for the Live Query functionality. Let's get it installed.
```sh
sudo apt-get install redis-server -y
```
## Install & configure Fleet
Finally, the linchpin - Fleet. Let's download the latest version. You can find the latest version here: https://github.com/fleetdm/fleet/releases/latest - make sure you download the main Fleet package and not `fleetctl` at this time.
```sh
wget https://github.com/fleetdm/fleet/releases/download/fleet-$VERSION/fleet_$VERSION_linux.tar.gz
tar -xf fleet_v*_linux.tar.gz # Extract the Fleet binary
sudo cp fleet_v*_linux/fleet /usr/bin/ # Copy the the Fleet binary to /usr/bin
fleet version # Sanity check to make sure it runs as expected
```
Next we will create the directory that will contain the config and installers, and create the config itself.
```sh
mkdir /etc/fleet
nano /etc/fleet/fleet.config
```
Use the following as a baseline for your Fleet config:
```yaml
mysql:
address: 127.0.0.1:3306
database: fleet
username: fleet
password: FleetPW!
redis:
address: 127.0.0.1:6379
server:
address: 0.0.0.0:4443
cert: /etc/letsencrypt/live/fleet.localhost.invalid/fullchain.pem
key: /etc/letsencrypt/live/fleet.localhost.invalid/privkey.pem
websockets_allow_unsafe_origin: true # This is needed for Live Query functionality to work with the nginx reverse proxy we are using
```
Next, let's run the `prepare db` command to complete the necessary database prep.
```sh
fleet prepare db --config /etc/fleet/fleet.config
```
### Setup systemd unit file
Now that we are ready to run Fleet, let's create a `systemd` unit file to manage Fleet as a service, and then go ahead and start the service:
```sh
sudo nano /etc/systemd/system/fleet.service # Use the example unit file below
sudo systemctl enable --now fleet.service
sudo systemctl status fleet.service
```
```sh
[Unit]
Description=fleet
After=network.target
[Service]
ExecStart=/usr/bin/fleet serve -c /etc/fleet/fleet.config
[Install]
WantedBy=multi-user.target
```
Finally, complete the Fleet setup via the web interface at https://fleet.localhost.invalid:9443
## fleetctl
fleetctl is a utility from Fleet that is used to manage Fleet from the command line. Let's download it and get it logged into our instance of Fleet. You can find the latest version here: https://github.com/fleetdm/fleet/releases/latest
```sh
wget https://github.com/fleetdm/fleet/releases/download/fleet-$VERSION/fleetctl_$VERSION_linux.tar.gz
tar -xf fleetctl_*_linux.tar.gz# Extract the fleetct binary
sudo cp fleetctl_v*_linux/fleetctl /usr/bin/ # Copy the the fleetctl binary to /usr/bin
/usr/bin/fleetctl --version # Sanity check to make sure it runs as expected
```
Next, we need to configure it to work with our local instance of Fleet and login to it.
```sh
fleetctl config set --address https://fleet.localhost.invalid::4443
fleetctl login
```
## Generate agents
Fleet ships with support for Orbit, a wrapper around osquery. Orbit makes configuration of osquery much simpler, offers auto-update functionality of osquery as well as additional tables developed by Fleet. In order to install an Orbit/osquery agent, you will need to generate an installer.
You can start the process of generating Orbit agent packages from the Fleet interface - click on the `Add Hosts` button. You can generate the packages anywhere that you have `fleetctl`, including on the server itself. Be sure to install the Docker engine if you need to generate installers for Windows.
## Load Fleet standard query library
Fleet has a library of queries that are useful in many different situations - https://fleetdm.com/docs/using-fleet/standard-query-library
Let's go ahead and load them - once this is complete, you can find them in the web interface under Queries.
```sh
git clone https://github.com/fleetdm/fleet.git
cd fleet
fleetctl apply -f docs/01-Using-Fleet/standard-query-library/standard-query-library.yml
```
<meta name="articleTitle" value="Deploy Fleet on Ubuntu">
<meta name="authorGitHubUsername" value="defensivedepth">
<meta name="authorFullName" value="Josh Brower">
<meta name="publishedOn" value="2024-06-12">
<meta name="category" value="guides">
<meta name="description" value="A guide to deploy Fleet and Elastic on Ubuntu.">
<meta name="articleImageUrl" value="../website/assets/images/articles/deploy-fleet-on-ubuntu-with-elastic-1600x900@2x.png">

114
articles/fleet-4.51.0.md Normal file
View file

@ -0,0 +1,114 @@
# Fleet 4.51.0 | Global activity webhook, macOS TCC table, and software self-service.
![Fleet 4.51.0](../website/assets/images/articles/fleet-4.51.0-1600x900@2x.png)
Fleet 4.51.0 is live. Check out the full [changelog](https://github.com/fleetdm/fleet/releases/tag/fleet-v4.51.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
* Global activity webhook
* macOS TCC table
* Software self-service
* Simplified APNs and ABM token uploads
## Global activity webhook
Fleet adds webhook support for global activities, broadening automation and real-time notification capabilities. This feature allows IT administrators to set up webhooks triggered by specific events within Fleet, such as changes in MDM features or re-enrollment activities. This also supports reporting mechanisms, enabling administrators to monitor the alignment between the number of devices enrolled and employees onboarded.
This update enhances operational efficiency by automating workflows and providing timely data, helping administrators manage device configurations and compliance more effectively. By leveraging webhooks for these critical events, Fleet ensures that administrators can maintain continuous oversight and respond swiftly to changes, ultimately bolstering the organization's device management and security frameworks.
## macOS TCC table
Fleet adds to its monitoring capabilities for macOS devices with support for querying the macOS TCC (Transparency, Consent, and Control) databases. This gives administrators valuable insights into applications' permissions on individual devices, particularly concerning accessing sensitive user data. The TCC framework is a critical component of macOS, designed to safeguard user privacy by managing app permissions across the system. With this update, Fleet enables IT teams to audit and verify that applications comply with organizational policies and privacy standards by accessing detailed, granular permission settings. This capability is essential for maintaining stringent security and privacy protocols, ensuring that only authorized applications can access sensitive information, and enhancing organizations' overall security posture by utilizing macOS within their fleets.
## Software self-service
Fleet aims to streamline the software installation process across organizations through software self-service. IT administrators can easily add software packages to Fleet and make them available for end-users to install via Fleet Desktop. Administrators can offer a curated list of pre-approved and organizationally vetted software directly to users, simplifying the installation process and ensuring compliance with organizational software standards. This addition not only empowers users by providing them with the autonomy to install necessary applications as needed but also ensures that all software deployed across the organization is secure and authorized, thereby maintaining high standards of IT security and operational efficiency.
## Simplified APNs and ABM token uploads
Fleet has simplified the integration of Apple Push Notification service (APNs) certificates and Apple Business Manager (ABM) tokens directly through its user interface. This update marks a significant shift from the previous requirement of using `fleetctl` commands and environmental variables for these tasks. IT administrators can effortlessly upload APNs certificates and ABM tokens via the Fleet UI, enhancing the setup process for managing Apple devices within their networks. This streamlined approach reduces the complexity of configuring necessary services for device management. It accelerates the deployment process, allowing administrators to focus more on strategic tasks than manual configurations. \
For self-managed users, the integration of these certificates requires a server private key, which is essential for activating macOS MDM features within Fleet. See Fleet's documentation for guidance on [configuring a private key](https://fleetdm.com/learn-more-about/fleet-server-private-key), which provides detailed instructions and best practices.
## Changes
### Endpoint Operations
- Added support for environment variables in configuration profiles for GitOps.
- `fleetctl gitops --dry-run` now errors on duplicate (or conflicting) global/team enroll secrets.
- Added `activities_webhook` configuration option to allow for a webhook to be called when an activity is recorded. This can be used to send activity data to external services. If the webhook response is a 429 error code, the webhook retries for up to 30 minutes.
- Added Tuxedo OS to the Linux distribution platform list.
### Device Management (MDM)
- **NOTE:** Added new required Fleet server config environment variable when MDM is enabled,
`FLEET_SERVER_PRIVATE_KEY`. This variable contains the private key used to encrypt the MDM
certificates and keys stored in Fleet. Learm more at
https://fleetdm.com/learn-more-about/fleet-server-private-key.
- Added MDM support for iPhone/iPad.
- Added software self-service support.
- Added query parameter `self_service` to filter the list of software titles and the list of a host's software so that only those available to install via self-service are returned.
- Added the device-authenticated endpoint `POST /device/{token}/software/install/{software_title_id}` to self-install software.
- Added new endpoints to configure ABM keypairs and tokens.
- Added `GET /fleet/mdm/apple/request_csr` endpoint, which returns the signed APNS CSR needed to activate Apple MDM.
- Added the ability to automatically log off and lock out `Administrator` users on Windows hosts.
- Added clearer error messages when attempting to set up Apple MDM without a server private key configured.
- Added UI for the global and host activities for self-service software installation.
- Updated UI to support new workflows for macOS MDM setup and credentials.
- Updated UI to support software self-service features.
- Updated UI controls page language and hid CTA button for users without access to turn on MDM.
### Vulnerability Management
- Updated the CIS policies for Windows 11 Enterprise from v2.0.0 (03-07-2023) to v3.0.0 (02-22-2024).
- Fleet now detects Ubuntu kernel vulnerabilities from the Canonical OVAL feed.
- Fleet now detects and reports vulnerabilities on Firefox ESR editions on macOS.
### Bug fixes and improvements
- Fixed a bug that might prevent enqueuing commands to renew SCEP certificates if the host was enrolled more than once.
- Prevented the `host_id`s field from being returned from the list labels endpoint.
- Improved software ingestion performance by deduplicating incoming software.
- Placed all form field label tooltips on top.
- Fixed a number of related issues with the filtering and sorting of the queries table.
- Added various optimizations to the rendering of the queries table.
- Fixed host query page styling bugs.
- Fixed a UI bug where "Wipe" action was not being hidden from observers.
- Fixed UI bug for builtin label names for selecting targets.
- Removed references to Administrator accounts in the comments of the Windows lock script.
## Fleet 4.50.2 (May 31, 2024)
### Bug fixes
* Fixed a critical bug where S3 operation were not possible on a different AWS account.
## Fleet 4.50.1 (May 29, 2024)
### Bug fixes
* Fixed a bug that might prevent enqueing commands to renew SCEP certificates if the host was enrolled more than once.
* Fixed a bug by preventing the `host_id`s field from being returned from the list labels endpoint.
* Fixed a number of related issues with the filtering and sorting of the queries table.
* Added various optimizations to the rendering of the queries table.
* Fixed a bug where Bulk Host Delete and Transfer now support status and labelID filters together.
* Added the ability to automatically log off and lock out `Administrator` users on Windows hosts.
* Removed references to Administrator accounts in the comments of the Windows lock script.
## 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.51.0.
<meta name="category" value="releases">
<meta name="authorFullName" value="JD Strong">
<meta name="authorGitHubUsername" value="spokanemac">
<meta name="publishedOn" value="2024-06-10">
<meta name="articleTitle" value="Fleet 4.51.0 | Global activity webhook, macOS TCC table, and software self-service.">
<meta name="articleImageUrl" value="../website/assets/images/articles/fleet-4.51.0-1600x900@2x.png">

2
articles/what-api-endpoints-to-expose-to-the-public-internet.md
View file

@ -61,7 +61,7 @@ If you would like to use Fleet's Windows MDM features, the following endpoints n
The `/api/*/fleet/*` endpoints accessed by the fleetd agent can use mTLS with the certificate provided via the `--fleet-tls-client-certificate` flag in the `fleetctl package` command.
The `/mdm/apple/mdm` and `/api/mdm/apple/enroll` endpoints can use mTLS with the [SCEP certificate issued by the Fleet server](https://fleetdm.com/docs/configuration/fleet-server-configuration#mdm-apple-scep-cert-bytes).
The `/mdm/apple/mdm` and `/api/mdm/apple/enroll` endpoints can use mTLS with the SCEP certificate issued by the Fleet server.
These endpoints don't use mTLS:
- `/mdm/apple/scep`

11
articles/windows-mdm-setup.md
View file

@ -12,15 +12,14 @@ To use automatic enrollment (aka zero-touch) features on Windows, follow instruc
Fleet uses a certificate and key pair to authenticate and manage interactions between Fleet and Windows host.
> If you're already using Fleet's macOS MDM features, you already have a SCEP certificate and key. Skip to step 2 and reuse the SCEP certificate and key as your WSTEP certificate and key.
How to generate a certificate and key:
If you're not using macOS MDM features, run the following command to download three files and send an email to you with an attached CSR file.
1. With [OpenSSL](https://www.openssl.org/) installed, open your Terminal (macOS) or PowerShell (Windows) and run the following command to create a key: `openssl genrsa --traditional -out fleet-mdm-win-wstep.key 4096`.
```
fleetctl generate mdm-apple --email <email> --org <org>
```
2. Create a certificate: `openssl req -x509 -new -nodes -key fleet-mdm-win-wstep.key -sha256 -days 3652 -out fleet-mdm-win-wstep.crt -subj '/CN=Fleet Root CA/C=US/O=Fleet.'`.
> Note: The default `openssl` binary installed on macOS is actually `LibreSSL`, which doesn't support the `--traditional` flag. To successfully generate these files, make sure you're using `OpenSSL` and not `LibreSSL`. You can check what your `openssl` command points to by running `openssl version`.
Save the SCEP certificate and SCEP key. These are your certificate and key. You can ignore the downloaded APNs key and the APNs CSR that was sent to your email.
### Step 2: Configure Fleet with your certificate and key

1
changes/10383-mdm-saved-certs-ui
View file

@ -1 +0,0 @@
- Updated UI to support new workflows for macOS MDM setup and credentials.

1
changes/11942-duplicated-software
View file

@ -1 +0,0 @@
Improved software ingestion performance by deduplicating incoming software.

2
changes/14722-activity-feed-webhooks
View file

@ -1,2 +0,0 @@
Added `activities_webhook` configuration option to allow for a webhook to be called when an activity is recorded. This can be used to send activity data to external services.
If the webhook response is a 429 error code, the webhook retries for up to 30 minutes.

1
changes/148940-app-os-vuln-matching Normal file
View file

@ -0,0 +1 @@
- Fleet now matches vulnerabilies for applications that include an OS scope [example](https://nvd.nist.gov/vuln/detail/CVE-2023-0400)

1
changes/16393-add-warning-log-duplicate-uuid Normal file
View file

@ -0,0 +1 @@
* Added warning server log when hosts are enrolling with duplicate hardware identifiers.

1
changes/16795-update-go
View file

@ -1 +0,0 @@
* Update Go version to go1.22.3

1
changes/17309-support-env-vars-profiles
View file

@ -1 +0,0 @@
* Support environment variables in configuration profiles for GitOps.

1
changes/17365-update-osquery-flags Normal file
View file

@ -0,0 +1 @@
* Update osquery flags with new flags added on 5.12.X.

1
changes/17387-soft-delete-host-script-and-software-install-results Normal file
View file

@ -0,0 +1 @@
* Use a "soft-delete" approach when deleting a host so that its script execution details are still available for the activities feed.

1
changes/17513-bulk-host-opts-filters
View file

@ -1 +0,0 @@
- Bulk Host Delete and Transfer now support status and labelID filters together

1
changes/17587-software-self-service-ui
View file

@ -1 +0,0 @@
- Updated UI to support software self-service features.

1
changes/17728-send-408-instead-of-500-for-apple-mdm-timeout Normal file
View file

@ -0,0 +1 @@
* Fixed the `/mdm/apple/mdm` endpoint so that it returns status code 408 (request timeout) instead of 500 (internal server error) when encountering a timeout reading the request body.

1
changes/17860-improve-license-expiration-banner
View file

@ -1 +0,0 @@
- UI: Updated look to license expiration banner

1
changes/18053-ubuntu-kernel-vuln-detection
View file

@ -1 +0,0 @@
- fleet now detects Ubuntu kernel vulnerabilities from the Canonical OVAL feed

1
changes/18119-iphone-ipad-support
View file

@ -1 +0,0 @@
* Added MDM support for iPhone/iPad.

1
changes/18447-firefox-esr
View file

@ -1 +0,0 @@
- detect and report vulnerabilities on Firefox ESR editions on macOS

1
changes/18461-windows-lock
View file

@ -1 +0,0 @@
- Adds the ability to automatically log off and lock out `Administrator` users on Windows hosts.

1
changes/18515-remove-host-ids-from-list-labels
View file

@ -1 +0,0 @@
- Prevent the `host_id`s field from being returned from the list labels endpoint.

1
changes/18534-support-rpm-upgrade Normal file
View file

@ -0,0 +1 @@
* Added support for upgrades to fleetd RPMs packages.

1
changes/18732-switch-teams-reset-page
View file

@ -1 +0,0 @@
- UI fix: Switching team resets to page 0 for all software and policy tables

1
changes/18733-vscode-false-pos Normal file
View file

@ -0,0 +1 @@
removed vscode false positive vulnerabilities

1
changes/18741-form-field-tooltip-positions
View file

@ -1 +0,0 @@
* Place all form field label tooltips on top

1
changes/18833-filter-software-by-self-service
View file

@ -1 +0,0 @@
* Added query parameter `self_service` to filter the list of software titles and the list of a host's software so that only those available to install via self-service are returned.

1
changes/18834-add-self-service-install-endpoint
View file

@ -1 +0,0 @@
* Added the device-authenticated endpoint `POST /device/{token}/software/install/{software_title_id}` to self-install software.

1
changes/18834-fleetctl-add-self-service-field
View file

@ -1 +0,0 @@
* Added the `self_service` field to `fleetctl apply` and `fleetctl gitops` YAML configuration files.

5
changes/18838-additional-db-optimizations
View file

@ -1,5 +0,0 @@
MySQL query optimizations:
- During software ingestion, switched to updating last_opened_at as a batch (for 1 host).
- Removed DELETE FROM software statement that ran for every host update (when software was deleted). The cleanup of unused software is now only done during the vulnerability job.
- `/api/v1/fleet/software/versions/:id` endpoint can return software even if it has been recently deleted from all hosts. During hourly cleanup, this software item will be removed from the database.
- Moved aggregated query stats calculations to read replica DB to reduce load on the master.

1
changes/18847-software-self-install-activities
View file

@ -1 +0,0 @@
* Added the `self_install` and `software_package` fields to the `installed_software` activity.

1
changes/18862-upgradeCIS-win11
View file

@ -1 +0,0 @@
* Updated the CIS policies for Windows 11 Enterprise fro v2.0.0 - 03-07-2023 to v3.0.0 - 02-22-2024

2
changes/18881-queries-table-filter-bugs
View file

@ -1,2 +0,0 @@
- Fix a number of related issues with the filtering and sorting of the queries table.
- Add various optimizations to the rendering of the queries table.

1
changes/18912-controls-language-and-cta-button-fix
View file

@ -1 +0,0 @@
- UI: Updates to controls page language and hide CTA button for users without access to turn on MDM

1
changes/18993-404-when-no-team-on-delete-team-policies Normal file
View file

@ -0,0 +1 @@
* Error with 404 when the user attempts to delete team policies for a non-existent team

1
changes/19000-zoominfo-icon Normal file
View file

@ -0,0 +1 @@
- Fixed UI bug where Zoom icon was displayed for ZoomInfo.

1
changes/19001-builtin-label-names-selecting-targets
View file

@ -1 +0,0 @@
- UI: Fix builtin label names for selecting targets

2
changes/19014-certs-endpoints
View file

@ -1,2 +0,0 @@
- Adds a `GET /fleet/mdm/apple/request_csr` endpoint, which returns the signed APNS CSR needed to
activate Apple MDM.

1
changes/19052-activity-feed-webhooks
View file

@ -1 +0,0 @@
* Added webhook for the activity feed.

1
changes/19072-additional-stats
View file

@ -1 +0,0 @@
- Added additional statistics items as part of our quality telemetry.

2
changes/19103-my-device-os-settings Normal file
View file

@ -0,0 +1,2 @@
- Fixed UI bug where error detail was overflowing the table in "OS settings" modal in "My device"
page UI.

1
changes/19129-fleetctl-preview-enroll-secrets Normal file
View file

@ -0,0 +1 @@
* Fixed bug in `fleetctl preview` caused by creating enroll secrets.

1
changes/19152-gitops-duplicate-enroll-secret
View file

@ -1 +0,0 @@
`fleetctl gitops --dry-run` now errors on duplicate (or conflicting) global/team enroll secrets.

1
changes/19171-host-query-bug-fixes
View file

@ -1 +0,0 @@
- Fix host query page styling bugs

1
changes/19179-bm
View file

@ -1 +0,0 @@
* Added new endpoints to configure ABM keypairs and tokens

1
changes/19184-activity-human-readable Normal file
View file

@ -0,0 +1 @@
- Fix activity without public IP to be human readable

1
changes/19197-fix-windows-remove-fleetd-script Normal file
View file

@ -0,0 +1 @@
* Fixed an issue with the Windows-specific `windows-remove-fleetd.ps1` script provided in the Fleet repository where running the script did remove `fleetd` but made it impossible to reinstall the agent.

3
changes/19267-bugfix-ui-wipe-menu
View file

@ -1,3 +0,0 @@
- Fixed UI bug where "Wipe" action was not being hidden from observers (note: this is only a
frontend bug and any observer that attempted to perform this action would be forbidden by the
backend).

1
changes/19272-live-query-lag
View file

@ -1 +0,0 @@
Live queries now work via UI with large (~1 second) replication lag (for master-replica DB setup).

0
orbit/changes/19284-modal-background-scrollbars → changes/19284-modal-background-scrollbars
View file

1
changes/19290-fix-make-slice-with-capacity Normal file
View file

@ -0,0 +1 @@
* Fixed a code linter issue where a slice was created non-empty and appended-to, instead of empty with the required capacity.

1
changes/19311-scep-renew
View file

@ -1 +0,0 @@
* Fixed a bug that might prevent enqueing commands to renew SCEP certificates if the host was enrolled more than once.

1
changes/19324-fix-panic-in-download-software Normal file
View file

@ -0,0 +1 @@
* Fixed a panic (API returning code 500) when the software installer exists in the database but the installer does not exist in the storage.

2
changes/19332-clear-secrets-with-gitops Normal file
View file

@ -0,0 +1,2 @@
* Enabled `fleetctl gitops` to create teams with no enroll secrets, or clear enroll secrets for an existing team. This is done by setting `team_settings.secrets` to nothing or to null or to an empty array ( `[]` ) in YAML.
* Enabled `fleetctl apply` to create teams with no enroll secrets, or clear enroll secrets for an existing team. This is done by setting `team.secrets` to an empty array in YAML.

3
changes/19348-software-host-details-page Normal file
View file

@ -0,0 +1,3 @@
Fixed host details page and device details page not showing the latest software.
Added `exclude_software` query parameter to the `/api/latest/fleet/hosts/:id` endpoint to exclude software from the response.

1
changes/19365-disable-ai-migration Normal file
View file

@ -0,0 +1 @@
* Disabled AI features on non-new installations upgrading from < 4.50.X to >= 4.51.X.

1
changes/19453-improve-software-installer-upload-endpoint Normal file
View file

@ -0,0 +1 @@
* Extended the timeout for the endpoint to upload a software installer (`POST /fleet/software/package`), and improved handling of the maximum size.

1
changes/19464-private-key-errors
View file

@ -1 +0,0 @@
- Adds clearer error messages when attempting to set up Apple MDM without a server private key configured.

1
changes/19500-scripts-cleanup Normal file
View file

@ -0,0 +1 @@
* Fixed a bug that prevented unused script contents to be periodically cleaned up from the database.

2
changes/19526-installers-bucket Normal file
View file

@ -0,0 +1,2 @@
- Adds S3 config variables with a `carves_` and `software_installers` prefix, which are used to
configure buckets for those features. The existing non-prefixed variables are kept for backwards compatibility.

1
changes/19528-dot-notation-bug-on-queries Normal file
View file

@ -0,0 +1 @@
* Fix queries with dot notation in the column name to show results

1
changes/19580-fix-linux-unlock-script-for-user-without-password Normal file
View file

@ -0,0 +1 @@
* Fixed the Linux unlock script to support passwordless users.

1
changes/add-tuxedo-os
View file

@ -1 +0,0 @@
* Added Tuxedo OS to the Linux distribution platform list.

1
changes/conf-6385-host-policy-table-fixes Normal file
View file

@ -0,0 +1 @@
- Host policy table can be sortable by response and View all host link preserves the team

1
changes/fix-s3-back-compat Normal file
View file

@ -0,0 +1 @@
- Fixes an issue with backwards compatibility with the deprecated `FLEET_S3_*` environment variables.

1
changes/issue-18847-add-ui-activities-for-self-service
View file

@ -1 +0,0 @@
- add UI for the global and host activities for self-service software installation

1
changes/issue-19433-render-0-value-as-number Normal file
View file

@ -0,0 +1 @@
- Makes the rendering of empty text cell values consistent. Also render the '0' value as a number instead of the default value `---`.

1
changes/issue-19555-dashboard-icon-fixes Normal file
View file

@ -0,0 +1 @@
- fix various icon misalignments on the dashboard page

1
changes/jve-fix-lock-script-typo
View file

@ -1 +0,0 @@
- Removes references to Administrator accounts in the comments of the Windows lock script.

2
changes/jve-pk-docs
View file

@ -1,2 +0,0 @@
- Updates the private key requirements to allow keys longer than 32 bytes
- Adds documentation around the new `FLEET_SERVER_PRIVATE_KEY` var

2
changes/post-apns-cert
View file

@ -1,2 +0,0 @@
- Adds 2 new endpoints: `POST` and `DELETE /fleet/mdm/apple/apns_certificate`. These endpoints let
users manage APNS certificates in Fleet.

2
changes/save-certs-encrypted
View file

@ -1,2 +0,0 @@
- Adds a new Fleet server config variable, `FLEET_SERVER_PRIVATE_KEY`. This variable contains the
private key used to encrypt the MDM certificates and keys stored in Fleet.

2
charts/fleet/Chart.yaml
View file

@ -8,7 +8,7 @@ version: v6.0.2
home: https://github.com/fleetdm/fleet
sources:
- https://github.com/fleetdm/fleet.git
appVersion: v4.50.2
appVersion: v4.51.1
dependencies:
- name: mysql
condition: mysql.enabled

14
charts/fleet/values.yaml
View file

@ -2,7 +2,7 @@
# All settings related to how Fleet is deployed in Kubernetes
hostName: fleet.localhost
replicas: 3 # The number of Fleet instances to deploy
imageTag: v4.50.2 # Version of Fleet to deploy
imageTag: v4.51.1 # Version of Fleet to deploy
podAnnotations: {} # Additional annotations to add to the Fleet pod
serviceAccountAnnotations: {} # Additional annotations to add to the Fleet service account
resources:
@ -201,14 +201,10 @@ gke:
# All of the environment variables that can be set for Fleet
environments:
# MDM Settings
# The following environment variables are used to configure Fleet to work with
# Apple's MDM service. These are optional and only required if you are using
# Fleet to manage Apple devices.
# To more information: https://fleetdm.com/docs/using-fleet/mdm-setup#step-3-configure-fleet-with-the-required-files
FLEET_MDM_APPLE_APNS_CERT_BYTES: ""
FLEET_MDM_APPLE_APNS_KEY_BYTES: ""
FLEET_MDM_APPLE_SCEP_CERT_BYTES: ""
FLEET_MDM_APPLE_SCEP_KEY_BYTES: ""
# The following environment variable is required if you are using
# Fleet's macOS MDM features.
# To more information: https://fleetdm.com/docs/using-fleet/fleet-server-configuration#server-private-key
FLEET_SERVER_PRIVATE_KEY: ""
## Section: Environment Variables from Secrets/CMs
# envsFrom:

25
cmd/fleet/main.go
View file

@ -73,14 +73,23 @@ func applyDevFlags(cfg *config.FleetConfig) {
}
cfg.S3 = config.S3Config{
Bucket: "carves-dev",
Region: "minio",
Prefix: "dev-prefix",
EndpointURL: "localhost:9000",
AccessKeyID: "minio",
SecretAccessKey: "minio123!",
DisableSSL: true,
ForceS3PathStyle: true,
CarvesBucket: "carves-dev",
CarvesRegion: "minio",
CarvesPrefix: "dev-prefix",
CarvesEndpointURL: "localhost:9000",
CarvesAccessKeyID: "minio",
CarvesSecretAccessKey: "minio123!",
CarvesDisableSSL: true,
CarvesForceS3PathStyle: true,
SoftwareInstallersBucket: "software-installers-dev",
SoftwareInstallersRegion: "minio",
SoftwareInstallersPrefix: "dev-prefix",
SoftwareInstallersEndpointURL: "localhost:9000",
SoftwareInstallersAccessKeyID: "minio",
SoftwareInstallersSecretAccessKey: "minio123!",
SoftwareInstallersDisableSSL: true,
SoftwareInstallersForceS3PathStyle: true,
}
cfg.Packaging.S3 = config.S3Config{

34
cmd/fleet/serve.go
View file

@ -196,7 +196,7 @@ the way that the Fleet server works.
}
ds = mds
if config.S3.Bucket != "" {
if config.S3.CarvesBucket != "" || config.S3.Bucket != "" {
carveStore, err = s3.NewCarveStore(config.S3, ds)
if err != nil {
initFatal(err, "initializing S3 carvestore")
@ -691,13 +691,16 @@ the way that the Fleet server works.
var softwareInstallStore fleet.SoftwareInstallerStore
if license.IsPremium() {
profileMatcher := apple_mdm.NewProfileMatcher(redisPool)
if config.S3.Bucket != "" {
if config.S3.SoftwareInstallersBucket != "" {
if config.S3.BucketsAndPrefixesMatch() {
level.Warn(logger).Log("msg", "the S3 buckets and prefixes for carves and software installers appear to be identical, this can cause issues")
}
store, err := s3.NewSoftwareInstallerStore(config.S3)
if err != nil {
initFatal(err, "initializing S3 software installer store")
}
softwareInstallStore = store
level.Info(logger).Log("msg", "using S3 software installer store", "bucket", config.S3.Bucket)
level.Info(logger).Log("msg", "using S3 software installer store", "bucket", config.S3.SoftwareInstallersBucket)
} else {
installerDir := os.TempDir()
if dir := os.Getenv("FLEET_SOFTWARE_INSTALLER_STORE_DIR"); dir != "" {
@ -860,7 +863,12 @@ the way that the Fleet server works.
if license.IsPremium() {
if err := cronSchedules.StartCronSchedule(
func() (fleet.CronSchedule, error) {
return cron.NewCalendarSchedule(ctx, instanceID, ds, 5*time.Minute, logger)
if config.Calendar.Periodicity > 0 {
config.Calendar.SetAlwaysReloadEvent(true)
} else {
config.Calendar.Periodicity = 5 * time.Minute
}
return cron.NewCalendarSchedule(ctx, instanceID, ds, config.Calendar, logger)
},
); err != nil {
initFatal(err, "failed to register calendar schedule")
@ -1019,7 +1027,7 @@ the way that the Fleet server works.
}
}
// We must wrap the Handler here to set special per-endpoint Write
// We must wrap the Handler here to set special per-endpoint Read/Write
// timeouts, so that we have access to the raw http.ResponseWriter.
// Otherwise, the handler is wrapped by the promhttp response delegator,
// which does not support the Unwrap call needed to work with
@ -1030,6 +1038,9 @@ the way that the Fleet server works.
// does not implement.
rootMux.HandleFunc("/api/", func(rw http.ResponseWriter, req *http.Request) {
if req.Method == http.MethodPost && strings.HasSuffix(req.URL.Path, "/fleet/scripts/run/sync") {
// when running a script synchronously, we wait a while for a script
// execution result, so the write timeout (to write the response)
// must be extended.
rc := http.NewResponseController(rw)
// add an additional 30 seconds to prevent race conditions where the
// request is terminated early.
@ -1037,6 +1048,19 @@ the way that the Fleet server works.
level.Error(logger).Log("msg", "http middleware failed to override endpoint write timeout", "err", err)
}
}
if req.Method == http.MethodPost && strings.HasSuffix(req.URL.Path, "/fleet/software/package") {
// when uploading a software installer, the file might be large so
// the read timeout (to read the full request body) must be extended.
rc := http.NewResponseController(rw)
// the frontend times out waiting for the upload after 2 minutes, so
// use that same timeout:
// https://www.figma.com/design/oQl2oQUG0iRkUy0YOxc307/%2314921-Deploy-security-agents-to-macOS%2C-Windows%2C-and-Linux-hosts?node-id=773-18032&t=QjEU6tc73tddNSqn-0
if err := rc.SetReadDeadline(time.Now().Add(2 * time.Minute)); err != nil {
level.Error(logger).Log("msg", "http middleware failed to override endpoint read timeout", "err", err)
}
req.Body = http.MaxBytesReader(rw, req.Body, service.MaxSoftwareInstallerSize)
}
apiHandler.ServeHTTP(rw, req)
})
rootMux.Handle("/", frontendHandler)

69
cmd/fleetctl/gitops_test.go
View file

@ -181,22 +181,29 @@ func TestBasicTeamGitOps(t *testing.T) {
CreatedAt: time.Now(),
Name: teamName,
}
var savedTeam *fleet.Team
ds.TeamByNameFunc = func(ctx context.Context, name string) (*fleet.Team, error) {
if name == teamName {
return team, nil
if name == teamName && savedTeam != nil {
return savedTeam, nil
}
return nil, nil
return nil, &notFoundError{}
}
ds.TeamFunc = func(ctx context.Context, tid uint) (*fleet.Team, error) {
if tid == team.ID {
return team, nil
return savedTeam, nil
}
return nil, nil
}
var enrolledTeamSecrets []*fleet.EnrollSecret
ds.NewTeamFunc = func(ctx context.Context, newTeam *fleet.Team) (*fleet.Team, error) {
newTeam.ID = team.ID
savedTeam = newTeam
enrolledTeamSecrets = newTeam.Secrets
return newTeam, nil
}
ds.IsEnrollSecretAvailableFunc = func(ctx context.Context, secret string, new bool, teamID *uint) (bool, error) {
return true, nil
}
var savedTeam *fleet.Team
ds.SaveTeamFunc = func(ctx context.Context, team *fleet.Team) (*fleet.Team, error) {
savedTeam = team
return team, nil
@ -205,10 +212,6 @@ func TestBasicTeamGitOps(t *testing.T) {
require.ElementsMatch(t, labels, []string{fleet.BuiltinLabelMacOS14Plus})
return map[string]uint{fleet.BuiltinLabelMacOS14Plus: 1}, nil
}
ds.SetOrUpdateMDMAppleDeclarationFunc = func(ctx context.Context, declaration *fleet.MDMAppleDeclaration) (*fleet.MDMAppleDeclaration, error) {
declaration.DeclarationUUID = uuid.NewString()
return declaration, nil
}
ds.DeleteMDMAppleDeclarationByNameFunc = func(ctx context.Context, teamID *uint, name string) error {
return nil
}
@ -216,16 +219,15 @@ func TestBasicTeamGitOps(t *testing.T) {
return nil
}
var enrolledSecrets []*fleet.EnrollSecret
ds.ApplyEnrollSecretsFunc = func(ctx context.Context, teamID *uint, secrets []*fleet.EnrollSecret) error {
enrolledSecrets = secrets
enrolledTeamSecrets = secrets
return nil
}
tmpFile, err := os.CreateTemp(t.TempDir(), "*.yml")
require.NoError(t, err)
t.Setenv("TEST_SECRET", secret)
t.Setenv("TEST_SECRET", "")
_, err = tmpFile.WriteString(
`
@ -235,7 +237,7 @@ policies:
agent_options:
name: ${TEST_TEAM_NAME}
team_settings:
secrets: [{"secret":"${TEST_SECRET}"}]
secrets: ${TEST_SECRET}
`,
)
require.NoError(t, err)
@ -255,8 +257,17 @@ team_settings:
_ = runAppForTest(t, []string{"gitops", "-f", tmpFile.Name()})
require.NotNil(t, savedTeam)
assert.Equal(t, teamName, savedTeam.Name)
require.Len(t, enrolledSecrets, 1)
assert.Equal(t, secret, enrolledSecrets[0].Secret)
assert.Empty(t, enrolledTeamSecrets)
// The previous run created the team, so let's rerun with an existing team
_ = runAppForTest(t, []string{"gitops", "-f", tmpFile.Name()})
assert.Empty(t, enrolledTeamSecrets)
// Add a secret
t.Setenv("TEST_SECRET", fmt.Sprintf("[{\"secret\":\"%s\"}]", secret))
_ = runAppForTest(t, []string{"gitops", "-f", tmpFile.Name()})
require.Len(t, enrolledTeamSecrets, 1)
assert.Equal(t, secret, enrolledTeamSecrets[0].Secret)
}
func TestFullGlobalGitOps(t *testing.T) {
@ -719,12 +730,18 @@ func TestBasicGlobalAndTeamGitOps(t *testing.T) {
ctx context.Context, tmID *uint, macProfiles []*fleet.MDMAppleConfigProfile, winProfiles []*fleet.MDMWindowsConfigProfile,
macDecls []*fleet.MDMAppleDeclaration,
) error {
assert.Empty(t, macProfiles)
assert.Empty(t, winProfiles)
return nil
}
ds.BatchSetScriptsFunc = func(ctx context.Context, tmID *uint, scripts []*fleet.Script) error {
assert.Empty(t, scripts)
return nil
}
ds.BatchSetScriptsFunc = func(ctx context.Context, tmID *uint, scripts []*fleet.Script) error { return nil }
ds.BulkSetPendingMDMHostProfilesFunc = func(
ctx context.Context, hostIDs []uint, teamIDs []uint, profileUUIDs []string, hostUUIDs []string,
) error {
assert.Empty(t, profileUUIDs)
return nil
}
ds.DeleteMDMAppleDeclarationByNameFunc = func(ctx context.Context, teamID *uint, name string) error {
@ -755,26 +772,26 @@ func TestBasicGlobalAndTeamGitOps(t *testing.T) {
}
ds.TeamFunc = func(ctx context.Context, tid uint) (*fleet.Team, error) {
if tid == team.ID {
return team, nil
return savedTeam, nil
}
return nil, nil
}
ds.TeamByNameFunc = func(ctx context.Context, name string) (*fleet.Team, error) {
if name == teamName {
return team, nil
if name == teamName && savedTeam != nil {
return savedTeam, nil
}
return nil, nil
return nil, &notFoundError{}
}
ds.NewTeamFunc = func(ctx context.Context, newTeam *fleet.Team) (*fleet.Team, error) {
newTeam.ID = team.ID
savedTeam = newTeam
enrolledTeamSecrets = newTeam.Secrets
return newTeam, nil
}
ds.SaveTeamFunc = func(ctx context.Context, team *fleet.Team) (*fleet.Team, error) {
savedTeam = team
return team, nil
}
ds.SetOrUpdateMDMAppleDeclarationFunc = func(ctx context.Context, declaration *fleet.MDMAppleDeclaration) (
*fleet.MDMAppleDeclaration, error,
) {
declaration.DeclarationUUID = uuid.NewString()
return declaration, nil
}
ds.BatchSetSoftwareInstallersFunc = func(ctx context.Context, teamID *uint, installers []*fleet.UploadSoftwareInstallerPayload) error {
return nil
}

4
cmd/fleetctl/preview.go
View file

@ -407,8 +407,8 @@ Use the stop and reset subcommands to manage the server and dependencies once st
return fmt.Errorf("Error retrieving enroll secret: %w", err)
}
if len(secrets.Secrets) != 1 {
return errors.New("Expected 1 active enroll secret")
if len(secrets.Secrets) == 0 {
return errors.New("Expected at least one enroll secret")
}
// disable analytics collection for preview

1
cmd/fleetctl/testdata/expectedGetTeamsYaml.yml vendored
View file

@ -29,6 +29,7 @@ spec:
enable_release_device_manually: false
macos_setup_assistant:
scripts: null
secrets: null
software: null
webhook_settings:
host_status_webhook: null

2
cmd/fleetctl/testdata/macosSetupExpectedTeam1And2Empty.yml vendored
View file

@ -29,6 +29,7 @@ spec:
deadline_days: null
grace_period_days: null
scripts: null
secrets: null
software: null
webhook_settings:
host_status_webhook: null
@ -63,6 +64,7 @@ spec:
deadline_days: null
grace_period_days: null
scripts: null
secrets: null
software: null
webhook_settings:
host_status_webhook: null

2
cmd/fleetctl/testdata/macosSetupExpectedTeam1And2Set.yml vendored
View file

@ -29,6 +29,7 @@ spec:
deadline_days: null
grace_period_days: null
scripts: null
secrets: null
software: null
webhook_settings:
host_status_webhook: null
@ -63,6 +64,7 @@ spec:
deadline_days: null
grace_period_days: null
scripts: null
secrets: null
software: null
webhook_settings:
host_status_webhook: null

1
cmd/fleetctl/testdata/macosSetupExpectedTeam1Empty.yml vendored
View file

@ -29,6 +29,7 @@ spec:
windows_settings:
custom_settings: null
scripts: null
secrets: null
software: null
webhook_settings:
host_status_webhook: null

1
cmd/fleetctl/testdata/macosSetupExpectedTeam1Set.yml vendored
View file

@ -28,6 +28,7 @@ spec:
deadline_days: null
grace_period_days: null
scripts: null
secrets: null
software: null
webhook_settings:
host_status_webhook: null

62
cmd/osquery-perf/agent.go
View file

@ -567,7 +567,7 @@ func newAgent(
SCEPChallenge: mdmSCEPChallenge,
SCEPURL: serverAddress + apple_mdm.SCEPPath,
MDMURL: serverAddress + apple_mdm.MDMPath,
})
}, "MacBookPro16,1")
// Have the osquery agent match the MDM device serial number and UUID.
serialNumber = macMDMClient.SerialNumber
hostUUID = macMDMClient.UUID
@ -2150,6 +2150,54 @@ func (a *agent) submitLogs(results []resultLog) error {
return nil
}
func runAppleIDeviceMDMLoop(i int, stats *Stats, model string, serverURL string, mdmSCEPChallenge string, mdmCheckInInterval time.Duration) {
udid := mdmtest.RandUDID()
mdmClient := mdmtest.NewTestMDMClientAppleDirect(mdmtest.AppleEnrollInfo{
SCEPChallenge: mdmSCEPChallenge,
SCEPURL: serverURL + apple_mdm.SCEPPath,
MDMURL: serverURL + apple_mdm.MDMPath,
}, model)
mdmClient.UUID = udid
mdmClient.SerialNumber = mdmtest.RandSerialNumber()
deviceName := fmt.Sprintf("%s-%d", model, i)
productName := model
if err := mdmClient.Enroll(); err != nil {
log.Printf("%s MDM enroll failed: %s", model, err)
stats.IncrementMDMErrors()
return
}
stats.IncrementMDMEnrollments()
mdmCheckInTicker := time.Tick(mdmCheckInInterval)
for range mdmCheckInTicker {
mdmCommandPayload, err := mdmClient.Idle()
if err != nil {
log.Printf("MDM Idle request failed: %s: %s", model, err)
stats.IncrementMDMErrors()
continue
}
stats.IncrementMDMSessions()
for mdmCommandPayload != nil {
stats.IncrementMDMCommandsReceived()
if mdmCommandPayload.Command.RequestType == "DeviceInformation" {
mdmCommandPayload, err = mdmClient.AcknowledgeDeviceInformation(udid, mdmCommandPayload.CommandUUID, deviceName, productName)
} else {
mdmCommandPayload, err = mdmClient.Acknowledge(mdmCommandPayload.CommandUUID)
}
if err != nil {
log.Printf("MDM Acknowledge request failed: %s: %s", model, err)
stats.IncrementMDMErrors()
break
}
}
}
}
// rows returns a set of rows for use in tests for query results.
func rows(num int) string {
b := strings.Builder{}
@ -2197,6 +2245,8 @@ func main() {
"windows_11_22H2_2861.tmpl": true,
"windows_11_22H2_3007.tmpl": true,
"ubuntu_22.04.tmpl": true,
"iphone_14.6.tmpl": true,
"ipad_13.18.tmpl": true,
}
allowedTemplateNames := make([]string, 0, len(validTemplateNames))
for k := range validTemplateNames {
@ -2349,6 +2399,16 @@ func main() {
tmpl = tmplss[i%len(tmplss)]
}
if tmpl.Name() == "iphone_14.6.tmpl" || tmpl.Name() == "ipad_13.18.tmpl" {
model := "iPhone 14,6"
if tmpl.Name() == "ipad_13.18.tmpl" {
model = "iPad 13,18"
}
go runAppleIDeviceMDMLoop(i, stats, model, *serverURL, *mdmSCEPChallenge, *mdmCheckInInterval)
time.Sleep(sleepTime)
continue
}
a := newAgent(i+1,
*serverURL,
*enrollSecret,

0
cmd/osquery-perf/ipad_13.18.tmpl Normal file
View file

0
cmd/osquery-perf/iphone_14.6.tmpl Normal file
View file

2
docs/Configuration/agent-configuration.md
View file

@ -144,7 +144,7 @@ You can verify that these flags have taken effect on the hosts by running a quer
> If you revoked an old enroll secret, this feature won't update for hosts that were added to Fleet using this old enroll secret. This is because Fleetd uses the enroll secret to receive new flags from Fleet. For these hosts, all existing features will work as expected.
For further documentation on how to rotate enroll secrets, please see [this guide](#rotating-enroll-secrets).
For further documentation on how to rotate enroll secrets, please see [this guide](https://fleetdm.com/docs/configuration/configuration-files#rotating-enroll-secrets).
If you prefer to deploy a new package with the updated enroll secret:

2
docs/Configuration/fleet-server-configuration.md
View file

@ -2807,7 +2807,7 @@ packaging:
> The [`server_private_key` configuration option](#server_private_key) is required for macOS MDM features.
> The Apple Push Notification service (APNs), SCEP, and Apple Business Manager (ABM) [configuration](https://github.com/fleetdm/fleet/fleet-v4.51.0/main/docs/Contributing/Configuration-for-contributors.md#mobile-device-management-mdm) are deprecated as of Fleet 4.51. They are maintained for backwards compatibility. Please upload your APNs certificate and ABM token in **Settings > Integrations MDM** and **Settings > Integrations > Automatic enrollment** respectively.
> The Apple Push Notification service (APNs), Simple Certificate Enrollment Protocol (SCEP), and Apple Business Manager (ABM) [certificate and key configuration](https://github.com/fleetdm/fleet/fleet-v4.51.0/main/docs/Contributing/Configuration-for-contributors.md#mobile-device-management-mdm) are deprecated as of Fleet 4.51. They are maintained for backwards compatibility. Please upload your APNs certificate and ABM token. Learn how [here](../Using%20Fleet/MDM-setup.md).
##### mdm.apple_scep_signer_validity_days

2
docs/Contributing/Configuration-for-contributors.md
View file

@ -414,7 +414,7 @@ The content of the Simple Certificate Enrollment Protocol (SCEP) certificate. An
-----END CERTIFICATE-----
```
The SCEP certificate/key pair [generated by Fleet](https://fleetdm.com/docs/using-fleet/MDM-setup#step-1-generate-the-required-files) expires every 10 years. It's recommended to never change these unless they were compromised.
The SCEP certificate/key pair generated by Fleet expires every 10 years. It's recommended to never change these unless they were compromised.
If your certificate/key pair was compromised and you change the pair, the disk encryption keys will no longer be viewable on all macOS hosts' **Host details** page until you turn disk encryption off and back on and the keys are [reset by the end user](https://fleetdm.com/docs/using-fleet/MDM-migration-guide#how-to-turn-on-disk-encryption).

83
docs/Contributing/Testing-and-local-development.md
View file

@ -505,95 +505,24 @@ To run your local server with the MDM features enabled, you need to get certific
### ABM setup
To enable the [DEP](https://github.com/fleetdm/fleet/blob/main/tools/mdm/apple/glossary-and-protocols.md#dep-device-enrollment-program) enrollment flow, the Fleet server needs three things:
1. A private key.
1. A certificate.
1. An encrypted token generated by Apple.
#### Private key, certificate, and encrypted token
To enable the [DEP](https://github.com/fleetdm/fleet/blob/main/tools/mdm/apple/glossary-and-protocols.md#dep-device-enrollment-program) enrollment flow, the Fleet server needs an encrypted token generated by Apple.
First ask @lukeheath to create an account for you in [ABM](https://github.com/fleetdm/fleet/blob/main/tools/mdm/apple/glossary-and-protocols.md#abm-apple-business-manager). You'll need an account to generate an encrypted token.
Once you have access to ABM, follow [these guided instructions](https://fleetdm.com/docs/using-fleet/mdm-setup#apple-business-manager-abm) in the user facing docs to generate the private key, certificate, and encrypted token.
Once you have access to ABM, follow [these guided instructions](https://fleetdm.com/docs/using-fleet/mdm-setup#apple-business-manager-abm) to get and upload the encrypted token.
### APNs and SCEP setup
The server also needs a private key + certificate to identify with Apple's [APNs](https://github.com/fleetdm/fleet/blob/main/tools/mdm/apple/glossary-and-protocols.md#apns-apple-push-notification-service) servers, and another for [SCEP](https://github.com/fleetdm/fleet/blob/main/tools/mdm/apple/glossary-and-protocols.md#scep-simple-certificate-enrollment-protocol).
The server also needs a certificate to identify with Apple's [APNs](https://github.com/fleetdm/fleet/blob/main/tools/mdm/apple/glossary-and-protocols.md#apns-apple-push-notification-service) servers.
To generate both, follow [these guided instructions](https://fleetdm.com/docs/using-fleet/mdm-macos-setup#apple-push-notification-service-apns).
To get a certificate and upload it, [these guided instructions](https://fleetdm.com/docs/using-fleet/mdm-macos-setup#apple-push-notification-service-apns).
Note that:
1. Fleet must be running to generate the certificates and keys.
1. Fleet must be running to generate the token and certificate.
2. You must be logged in to Fleet as a global admin. See [Building Fleet](./Building-Fleet.md) for details on getting Fleet setup locally.
3. To login into https://identity.apple.com/pushcert you can use your ABM account generated in the previous step.
4. Save all the certificates and keys in a safe place.
Internally, the certificates are generated using this flow. Note that the fleet sails API base url can be changed using the `TEST_FLEETDM_API_URL` environment variable.
```mermaid
sequenceDiagram
participant user as user email
participant fleetctl as fleetctl
participant server as fleet server
participant fleetdm as fleetdm.com sails app
participant apple as identity.apple.com
link apple: PushCert @ https://identity.apple.com/pushcert
note over fleetctl: fleetctl login
fleetctl->>+server: login
server-->>-fleetctl: token
note over fleetctl: fleetctl generate mdm_apple
fleetctl->>+server: generate certificates
server->>server: generate self-signed SCEP cert & key
server->>server: generate APNs key
server->>server: generate APNs CSR
server-)+fleetdm: request vendor signature on APNs CSR
server-->>-fleetctl: SCEP cert, SCEP key, APNs key
note over fleetdm: calls /ee/tools/mdm/cert
fleetdm--)-user: vendor-signed APNs CSR
user->>+apple: vendor-signed APNs CSR
note right of apple: managed through web ui
apple-->>-user: Apple-signed APNs certificate
```
Another option, if for some reason, generating the certificates and keys fails or you don't have a supported email address handy is to use `openssl` to generate your SCEP key pair:
```sh
$ openssl genrsa -out fleet-mdm-apple-scep.key 4096
$ openssl req -x509 -new -nodes -key fleet-mdm-apple-scep.key -sha256 -days 1826 -out fleet-mdm-apple-scep.crt -subj '/CN=Fleet Root CA/C=US/O=Fleet DM.'
```
### Running the server
Try to store all the certificates and tokens you generated in the earlier steps together in a safe place outside of the repo, then start the server with:
```sh
FLEET_MDM_APPLE_SCEP_CHALLENGE=scepchallenge \
FLEET_MDM_APPLE_SCEP_CERT=/path/to/fleet-mdm-apple-scep.crt \
FLEET_MDM_APPLE_SCEP_KEY=/path/to/fleet-mdm-apple-scep.key \
FLEET_MDM_APPLE_BM_SERVER_TOKEN=/path/to/dep_encrypted_token.p7m \
FLEET_MDM_APPLE_BM_CERT=/path/to/fleet-apple-mdm-bm-public-key.crt \
FLEET_MDM_APPLE_BM_KEY=/path/to/fleet-apple-mdm-bm-private.key \
FLEET_MDM_APPLE_APNS_CERT=/path/to/mdmcert.download.push.pem \
FLEET_MDM_APPLE_APNS_KEY=/path/to/mdmcert.download.push.key \
./build/fleet serve --dev --dev_license --logging_debug
```
Note: if you need to enroll VMs using MDM, the server needs to run behind TLS with a valid certificate. In a separate terminal window/tab, create a local tunnel to your server using `ngrok` (`brew install ngrok/ngrok/ngrok` if you don't have it.)
```sh
ngrok http https://localhost:8080
```
> NOTE: If this is your first time using ngrok this command will fail and you will see a message
> about signing up. Open the sign up link and complete the sign up flow. You can rerun the same command
> and ngrok should work this time. After this open the forwarding link, you will be asked to confirm that you'd like
> to be forwarded to your local server and should accept.
Don't forget to edit your Fleet server settings (through the UI or `fleetctl`) to use the URL `ngrok` provides to you. You need to do this whenever you restart `ngrok`.
4. Save the token and certificate in a safe place.
### Testing MDM

158
docs/REST API/rest-api.md
View file

@ -1,4 +1,4 @@
# REST API
# REST API
- [Authentication](#authentication)
- [Activities](#activities)
@ -880,6 +880,7 @@ None.
"apple_bm_terms_expired": false,
"enabled_and_configured": true,
"windows_enabled_and_configured": true,
"enable_disk_encryption": true,
"macos_updates": {
"minimum_version": "12.3.1",
"deadline": "2022-01-01"
@ -889,11 +890,20 @@ None.
"grace_period_days": 1
},
"macos_settings": {
"custom_settings": ["path/to/profile1.mobileconfig"],
"enable_disk_encryption": true
"custom_settings": [
{
"path": "path/to/profile1.mobileconfig",
"labels": ["Label 1", "Label 2"]
}
]
},
"windows_settings": {
"custom_settings": ["path/to/profile2.xml"],
"custom_settings": [
{
"path": "path/to/profile2.xml",
"labels": ["Label 3", "Label 4"]
}
],
},
"scripts": ["path/to/script.sh"],
"end_user_authentication": {
@ -983,6 +993,10 @@ None.
"enable_vulnerabilities_webhook":true,
"destination_url": "https://server.com",
"host_batch_size": 1000
},
"activities_webhook":{
"enable_activities_webhook":true,
"destination_url": "https://server.com"
}
},
"integrations": {
@ -1098,6 +1112,8 @@ Modifies the Fleet's configuration with the supplied information.
| enable_vulnerabilities_webhook | boolean | body | _webhook_settings.vulnerabilities_webhook settings_. Whether or not the vulnerabilities webhook is enabled. |
| destination_url | string | body | _webhook_settings.vulnerabilities_webhook settings_. The URL to deliver the webhook requests to. |
| host_batch_size | integer | body | _webhook_settings.vulnerabilities_webhook settings_. Maximum number of hosts to batch on vulnerabilities webhook requests. The default, 0, means no batching (all vulnerable hosts are sent on one request). |
| enable_activities_webhook | boolean | body | _webhook_settings.activities_webhook settings_. Whether or not the activity feed webhook is enabled. |
| destination_url | string | body | _webhook_settings.activities_webhook settings_. The URL to deliver the webhook requests to. |
| enable_software_vulnerabilities | boolean | body | _integrations.jira[] settings_. Whether or not Jira integration is enabled for software vulnerabilities. Only one vulnerability automation can be enabled at a given time (enable_vulnerabilities_webhook and enable_software_vulnerabilities). |
| enable_failing_policies | boolean | body | _integrations.jira[] settings_. Whether or not Jira integration is enabled for failing policies. Only one failing policy automation can be enabled at a given time (enable_failing_policies_webhook and enable_failing_policies). |
| url | string | body | _integrations.jira[] settings_. The URL of the Jira server to integrate with. |
@ -1216,6 +1232,7 @@ Note that when making changes to the `integrations` object, all integrations mus
"apple_bm_enabled_and_configured": false,
"enabled_and_configured": false,
"windows_enabled_and_configured": false,
"enable_disk_encryption": true,
"macos_updates": {
"minimum_version": "12.3.1",
"deadline": "2022-01-01"
@ -1225,21 +1242,24 @@ Note that when making changes to the `integrations` object, all integrations mus
"grace_period_days": 1
},
"macos_settings": {
"custom_settings": {
"path": "path/to/profile1.mobileconfig",
"labels": ["Label 1", "Label 2"]
},
{
"path": "path/to/profile2.json",
"labels": ["Label 3", "Label 4"]
},
"enable_disk_encryption": true
"custom_settings": [
{
"path": "path/to/profile1.mobileconfig",
"labels": ["Label 1", "Label 2"]
},
{
"path": "path/to/profile2.json",
"labels": ["Label 3", "Label 4"]
},
]
},
"windows_settings": {
"custom_settings": {
"path": "path/to/profile3.xml",
"labels": ["Label 1", "Label 2"]
}
"custom_settings": [
{
"path": "path/to/profile3.xml",
"labels": ["Label 1", "Label 2"]
}
]
},
"end_user_authentication": {
"entity_id": "",
@ -1300,6 +1320,10 @@ Note that when making changes to the `integrations` object, all integrations mus
"enable_vulnerabilities_webhook":true,
"destination_url": "https://server.com",
"host_batch_size": 1000
},
"activities_webhook":{
"enable_activities_webhook":true,
"destination_url": "https://server.com"
}
},
"integrations": {
@ -5318,7 +5342,7 @@ Deletes the custom MDM setup enrollment profile assigned to a team or no team.
### Get manual enrollment profile
Retrieves the manual enrollment profile for macOS hosts. Install this profile on macOS hosts to turn on MDM features manually.
Retrieves an unsigned manual enrollment profile for macOS hosts. Install this profile on macOS hosts to turn on MDM features manually.
`GET /api/v1/fleet/enrollment_profiles/manual`
@ -6012,29 +6036,19 @@ For example, a policy might ask “Is Gatekeeper enabled on macOS devices?“ Th
### Add policy
There are two ways of adding a policy:
1. Preferred: By setting `name`, `query`, and `description`.
2. Legacy: By setting `query_id` to reuse the data of an existing query. If `query_id` is set,
then `query` must not be set, and `name` and `description` are ignored.
An error is returned if both `query` and `query_id` are set on the request.
`POST /api/v1/fleet/global/policies`
#### Parameters
| Name | Type | In | Description |
| ---------- | ------- | ---- | ------------------------------------ |
| name | string | body | The query's name. |
| query | string | body | The query in SQL. |
| description | string | body | The query's description. |
| name | string | body | The policy's name. |
| query | string | body | The policy's query in SQL. |
| description | string | body | The policy's description. |
| resolution | string | body | The resolution steps for the policy. |
| query_id | integer | body | An existing query's ID (legacy). |
| 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. |
Either `query` or `query_id` must be provided.
#### Example (preferred)
`POST /api/v1/fleet/global/policies`
@ -6079,47 +6093,6 @@ Either `query` or `query_id` must be provided.
}
```
#### Example (legacy)
`POST /api/v1/fleet/global/policies`
#### Request body
```json
{
"query_id": 12
}
```
Where `query_id` references an existing `query`.
##### Default response
`Status: 200`
```json
{
"policy": {
"id": 43,
"name": "Gatekeeper enabled",
"query": "SELECT 1 FROM gatekeeper WHERE assessments_enabled = 1;",
"description": "Checks if gatekeeper is enabled on macOS devices",
"critical": true,
"author_id": 42,
"author_name": "John",
"author_email": "john@example.com",
"team_id": null,
"resolution": "Resolution steps",
"platform": "darwin",
"created_at": "2022-03-17T20:15:55Z",
"updated_at": "2022-03-17T20:15:55Z",
"passing_host_count": 0,
"failing_host_count": 0,
"host_count_updated_at": null
}
}
```
### Remove policies
`POST /api/v1/fleet/global/policies/delete`
@ -6500,11 +6473,10 @@ The semantics for creating a team policy are the same as for global policies, se
| Name | Type | In | Description |
| ---------- | ------- | ---- | ------------------------------------ |
| id | integer | path | Defines what team ID to operate on. |
| name | string | body | The query's name. |
| query | string | body | The query in SQL. |
| description | string | body | The query's description. |
| name | string | body | The policy's name. |
| query | string | body | The policy's query in SQL. |
| description | string | body | The policy's description. |
| resolution | string | body | The resolution steps for the policy. |
| query_id | integer | body | An existing query's ID (legacy). |
| 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. |
@ -8164,7 +8136,7 @@ Download a software package.
| ---- | ------- | ---- | -------------------------------------------- |
| software_title_id | integer | path | **Required**. The ID of the software title to download software package.|
| team_id | integer | form | **Required**. The team ID. Downloads a software package added to the specified team. |
| alt | integer | path | **Required**. If specified and set to "media", downloads the specified software package. |
| alt | integer | query | **Required**. If specified and set to "media", downloads the specified software package. |
#### Example
@ -9009,6 +8981,7 @@ _Available in Fleet Premium_
}
},
"mdm": {
"enable_disk_encryption": true,
"macos_updates": {
"minimum_version": "12.3.1",
"deadline": "2022-01-01"
@ -9018,11 +8991,20 @@ _Available in Fleet Premium_
"grace_period_days": 1
},
"macos_settings": {
"custom_settings": ["path/to/profile1.mobileconfig"],
"enable_disk_encryption": false
"custom_settings": [
{
"path": "path/to/profile1.mobileconfig",
"labels": ["Label 1", "Label 2"]
}
]
},
"windows_settings": {
"custom_settings": ["path/to/profile2.xml"],
"custom_settings": [
{
"path": "path/to/profile2.xml",
"labels": ["Label 3", "Label 4"]
}
],
},
"macos_setup": {
"bootstrap_package": "",
@ -9293,6 +9275,7 @@ _Available in Fleet Premium_
}
},
"mdm": {
"enable_disk_encryption": true,
"macos_updates": {
"minimum_version": "12.3.1",
"deadline": "2022-01-01"
@ -9302,11 +9285,20 @@ _Available in Fleet Premium_
"grace_period_days": 1
},
"macos_settings": {
"custom_settings": ["path/to/profile1.mobileconfig"],
"enable_disk_encryption": false
"custom_settings": [
{
"path": "path/to/profile1.mobileconfig",
"labels": ["Label 1", "Label 2"]
}
]
},
"windows_settings": {
"custom_settings": ["path/to/profile2.xml"],
"custom_settings": [
{
"path": "path/to/profile2.xml",
"labels": ["Label 3", "Label 4"]
}
],
},
"macos_setup": {
"bootstrap_package": "",

4
docs/Using Fleet/MDM-commands.md
View file

@ -1,6 +1,6 @@
# Commands
In Fleet you can run MDM commands to take action on your macOS and Windows hosts, like restarting the host, remotely.
In Fleet you can run MDM commands to take action on your macOS, iOS, iPadOS, and Windows hosts, like restarting the host, remotely.
## Custom commands
@ -85,7 +85,7 @@ You can view a list of the 1,000 latest commands:
The command ID can be used to view command results as documented in [step 4 of the previous section](#step-4-view-the-commands-results).
The possible statuses for macOS hosts are the following:
The possible statuses for macOS, iOS, and iPadOS hosts are the following:
* Pending: the command has yet to run on the host. The host will run the command the next time it comes online.
* NotNow: the host responded with "NotNow" status via the MDM protocol: the host received the command, but couldn’t execute it. The host will try to run the command the next time it comes online.

260
docs/Using Fleet/MDM-setup.md
View file

@ -1,225 +1,28 @@
# Setup
To turn on macOS MDM features, follow the instructions on this page to connect Fleet to Apple Push Notification service (APNs).
To turn on macOS, iOS, and iPadOS MDM features, follow the instructions on this page to connect Fleet to Apple Push Notification service (APNs).
To use automatic enrollment (aka zero-touch) features on macOS, follow instructions to connect Fleet with Apple Business Manager (ABM).
To use automatic enrollment (aka zero-touch) features on macOS, iOS, and iPadOS, follow instructions to connect Fleet with Apple Business Manager (ABM).
To turn on Windows MDM features, head to this [Windows MDM setup article](https://fleetdm.com/guides/windows-mdm-setup).
## Apple Push Notification service (APNs)
Apple uses APNs to authenticate and manage interactions between Fleet and the host.
Apple uses APNs to authenticate and manage interactions between Fleet and hosts.
This section will show you how to:
1. Generate the files to connect Fleet to APNs.
2. Generate an APNs certificate from Apple Push Certificates Portal.
3. Configure Fleet with the required files.
To connect Fleet to APNs or renew APNs, head to the **Settings > Integrations > Mobile device management (MDM)** page.
### Step 1: generate the required files
For the MDM protocol to function, we need to generate the four following files:
- APNs certificate
- APNs private key
- Simple Certificate Enrollment Protocol (SCEP) certificate
- SCEP private key
The APNs certificates serve as authentication between Fleet and Apple, while the SCEP certificates serve as authentication between Fleet and hosts.
> To prevent abuse, please use your work email. If your email isn't accepted, please make sure it's not on this [list of blocked emails](https://github.com/fleetdm/fleet/blob/d5df23964b0b52f1d442b66ffe4451dc2a9ef969/website/api/controllers/deliver-apple-csr.js#L60).
Use either of the following methods to generate the necessary files:
#### Fleet UI
1. Navigate to the **Settings > Integrations > Mobile device management (MDM)** page.
2. Under **Apple Push Certificates Portal**, select **Request**, then fill out the form. This should generate three files and send an email to you with an attached CSR file.
#### Fleetctl CLI
Run the following command to download three files and send an email to you with an attached CSR file.
```sh
fleetctl generate mdm-apple --email <email> --org <org>
```
### Step 2: generate an APNs certificate
1. Log in to or enroll in [Apple Push Certificates Portal](https://identity.apple.com).
2. Select **Create a Certificate**.
3. Upload your CSR and input a friendly name, such as "Fleet."
4. Download the APNs certificate.
> **Important:** Take note of the Apple ID you use to sign into Apple Push Certificates Portal. You'll need to use the same Apple ID when renewing your APNs certificate.
### Step 3: configure Fleet with the generated files
Restart the Fleet server with the contents of the APNs certificate, APNs private key, SCEP certificate, and SCEP private key in the following environment variables:
> Note: Any environment variable that ends in `_BYTES` expects the file's actual content to be passed in, not a path to the file. If you want to pass in a file path, remove the `_BYTES` suffix from the environment variable.
* [FLEET_MDM_APPLE_APNS_CERT_BYTES](https://fleetdm.com/docs/deploying/configuration#mdm-apple-apns-cert-bytes)
* [FLEET_MDM_APPLE_APNS_KEY_BYTES](https://fleetdm.com/docs/deploying/configuration#mdm-apple-apns-key-bytes)
* [FLEET_MDM_APPLE_SCEP_CERT_BYTES](https://fleetdm.com/docs/deploying/configuration#mdm-apple-scep-cert-bytes)
* [FLEET_MDM_APPLE_SCEP_KEY_BYTES](https://fleetdm.com/docs/deploying/configuration#mdm-apple-scep-key-bytes)
* [FLEET_MDM_APPLE_SCEP_CHALLENGE](https://fleetdm.com/docs/deploying/configuration#mdm-apple-scep-challenge)
> You do not need to provide the APNs CSR which was emailed to you.
### Step 4: confirm that Fleet is set up correctly
Use either of the following methods to confirm that Fleet is set up. You should see information about the APNs certificate such as serial number and renewal date.
#### Fleet UI
Navigate to the **Settings > Integrations > Mobile device management (MDM)** page.
#### Fleetctl CLI
```
fleetctl get mdm-apple
```
## Renewing APNs
> **Important:** Apple requires that APNs certificates are renewed annually.
> Apple requires that APNs certificates are renewed annually.
> - If your certificate expires, you will have to turn MDM off and back on for all macOS hosts.
> - Be sure to use the same Apple ID from year-to-year. If you don't, you will have to turn MDM off and back on for all macOS hosts.
This section will guide you through how to:
1. Generate the files required to renew your APNs certificate.
2. Renew your APNs certificate in Apple Push Certificates Portal.
3. Configure Fleet with the required files.
4. Confirm that Fleet is set up correctly.
Use either of the following methods to see your APNs certificate's renewal date and other important information:
#### Fleet UI
Navigate to the **Settings > Integrations > Mobile device management (MDM)** page.
#### Fleetctl CLI
```sh
fleetctl get mdm-apple
```
### Step 1: generate the required files
- A new APNs certificate.
Run the following command in `fleetctl`. This will download three files and send an email to you with an attached CSR file. You may ignore the APNs key, SCEP certificate, and SCEP key as you do not need these to renew APNs.
```sh
fleetctl generate mdm-apple --email <email> --org <org>
```
### Step 2: renew APNs certificate
1. Log in to or enroll in [Apple Push Certificates Portal](https://identity.apple.com) using the same Apple ID you used to get your original APNs certificate.
2. Click **Renew** next to your certificate (make sure that the certificate's **Common Name (CN)** matches the one presented in Fleet).
3. Upload your CSR.
4. Download the new APNs certificate.
### Step 3: configure Fleet with the generated files
Restart the Fleet server with the contents of the APNs certificate in the following environment variable:
* [FLEET_MDM_APPLE_APNS_CERT_BYTES](https://fleetdm.com/docs/deploying/configuration#mdm-apple-apns-cert-bytes)
### Step 4: confirm that Fleet is set up correctly
Use either of the following methods to confirm that Fleet is set up:
#### Fleet UI:
1. Navigate to the **Settings > Integrations > Mobile device management (MDM)** page.
2. Follow the on-screen instructions in the **Apple Push Certificates Portal** section.
#### Fleetctl CLI:
Run the following command. You should see information about the new APNs certificate such as serial number and renewal date.
```sh
fleetctl get mdm-apple
```
## Renewing SCEP
The SCEP certificates generated by Fleet and uploaded to the environment variables expire every 10 years. To renew them, regenerate the keys and update the relevant environment variables.
## Apple Business Manager (ABM)
> Available in Fleet Premium
By connecting Fleet to ABM, Macs purchased through Apple or an authorized reseller can automatically enroll to Fleet when they’re first unboxed and set up by your end user.
To connect Fleet to ABM or renew ABM, head to the **Settings > Integrations > Automatic enrollment > Apple Business Manager** page.
New or wiped macOS hosts that are in ABM, before they've been set up, appear in Fleet with **MDM status** set to "Pending".
This section will guide you through how to:
1. Generate certificate and private key for ABM
2. Create a new MDM server record for Fleet in ABM
3. Download the MDM server token from ABM
4. Upload the server token, certificate, and private key to the Fleet server
5. Set the new MDM server as the auto-enrollment server for Macs in ABM
### Step 1: generate the required certificate and private key
User either of the following methods to generate a certificate and private key pair. This pair is how Fleet authenticates itself to ABM:
#### Fleet UI:
1. Navigate to the **Settings > Integrations > Mobile device management (MDM)** page.
2. Under **Apple Business Manager**, click the "Download" button
#### Fleetctl CLI:
```sh
fleetctl generate mdm-apple-bm
```
### Step 2: create a new MDM server in ABM
Create an MDM server record in ABM which represents Fleet:
1. Log in to or enroll in [ABM](https://business.apple.com)
2. Click your name at the bottom left of the screen
3. Click **Preferences**
4. Click **MDM Server Assignment**
5. Click the **Add** button at the top
6. Enter a name for the server such as "Fleet"
7. Upload the certificate generated in Step 1
### Step 3: download the server token
In the details page of the newly created server, click **Download Token** at the top. You should receive a `.p7m` file.
### Step 4: upload server token, certificate, and private key to Fleet
With the three generated files, we now give them to the Fleet server so that it can authenticate itself to ABM.
Restart the Fleet server with the contents of the server token, certificate, and private key in following environment variables:
* [FLEET_MDM_APPLE_BM_SERVER_TOKEN_BYTES](https://fleetdm.com/docs/deploying/configuration#mdm-apple-bm-server-token-bytes)
* [FLEET_MDM_APPLE_BM_CERT_BYTES](https://fleetdm.com/docs/deploying/configuration#mdm-apple-bm-cert-bytes)
* [FLEET_MDM_APPLE_BM_KEY_BYTES](https://fleetdm.com/docs/deploying/configuration#mdm-apple-bm-key-bytes)
### Step 3: confirm that Fleet is set up correctly
Use either of the following methods to confirm that Fleet is set up correctly. You should see information about the ABM server token such as organization name and renewal date.
#### Fleet UI:
1. Navigate to the **Settings > Integrations > Mobile device management (MDM)** page.
2. Navigate to the **Apple Business Manager** section.
#### Fleetctl CLI:
```sh
fleetctl get mdm-apple
```
### Step 5: set Fleet to be the MDM server for Macs in ABM
Set Fleet to be the MDM for all future Macs purchased via Apple or an authorized reseller:
After connecting Fleet to ABM, set Fleet to be the MDM for all Macs:
1. Log in to [Apple Business Manager](https://business.apple.com)
2. Click your profile icon in the bottom left
@ -227,57 +30,12 @@ Set Fleet to be the MDM for all future Macs purchased via Apple or an authorized
4. Click **MDM Server Assignment** and click **Edit** next to **Default Server Assignment**.
5. Switch **Mac** to Fleet.
### Step 6: set the default team for hosts enrolled via ABM
New or wiped macOS, iOS, and iPadOS hosts that are in ABM, before they've been set up, appear in Fleet with **MDM status** set to "Pending".
All hosts that automatically enroll will be assigned to the default team. If no default team is set, then the host will be placed in "No team".
All macOS hosts that automatically enroll will be assigned to the default team. If no default team is set, then the host will be placed in "No team".
> A host can be transferred to a new (not default) team before it enrolls. In the Fleet UI, you can do this under **Settings** > **Teams**.
Use either of the following methods to change the default team:
#### Fleet UI
1. Navigate to the **Settings > Integrations > Mobile device management (MDM)** page.
2. In the Apple Business Manager section, select the **Edit team** button next to **Default team**.
3. Choose a team and select **Save**.
#### Fleetctl CLI
1. Create a `config` YAML document if you don't have one already. Learn how [here](./configuration-files/README.md#organization-settings). This document is used to change settings in Fleet.
2. Set the `mdm.apple_bm_default_team` configuration option to the desired team's name.
3. Run the `fleetctl apply -f <your-YAML-file-here>` command.
## Renewing ABM
> Apple expires ABM server tokens certificates once every year or whenever the account that downloaded the token has their password changed.
Use either of the following methods to see your ABM renewal date and other important information:
#### Fleet UI
1. Navigate to the **Settings > Integrations > Mobile device management (MDM)** page.
2. Look at the **Apple Business Manager** section.
#### Fleetctl CLI
```sh
fleetctl get mdm-apple
```
If you have configured Fleet with an Apple Business Manager server token for mobile device management (a Fleet Premium feature), you will eventually need to renew that token. [As documented in the Apple Business Manager User Guide](https://support.apple.com/en-ca/guide/apple-business-manager/axme0f8659ec/web), the token expires after a year or whenever the account that downloaded the token has their password changed.
To renew the token:
1. Log in to [business.apple.com](https://business.apple.com)
2. Select Fleet's MDM server record
3. Download a new token for that server record
4. In your Fleet server, update the environment variable [FLEET_MDM_APPLE_BM_SERVER_TOKEN_BYTES](https://fleetdm.com/docs/deploying/configuration#mdm-apple-bm-server-token-bytes)
5. Restart the Fleet server
<meta name="pageOrderInSection" value="1500">
<meta name="title" value="Setup">
<meta name="description" value="Learn how to turn on MDM features in Fleet.">

42
docs/Using Fleet/segment-hosts.md
View file

@ -1,46 +1,36 @@
# Segment hosts
`Applies only to Fleet Premium`
_Available in Fleet Premium_
```
ℹ️ In Fleet 4.0, Teams were introduced.
```
In Fleet, you can group hosts together in a "team" in Fleet. This way, you can apply queries, policies, scripts, and more that are tailored to the hosts' risk/compliance needs.
- [Overview](#overview)
- [Best practice](#best-practice)
- [Transfer hosts to a team](#transfer-hosts-to-a-team)
A host can only belong to one team.
## Overview
You can give users access to only some teams.
In Fleet, you can group hosts together in a team.
Then, you can give users access to only some teams.
This means you manage permissions so that some users can only run queries and manage hosts on the teams these users have access to.
You can manage teams in the Fleet UI by selecting **Settings** > **Teams** in the top navigation. From there, you can add or remove teams, manage user access to teams, transfer hosts, or modify team settings.
You can manage teams by selecting your avatar in the top navigation and then **Settings > Teams**.
## Best practice
The best practice is to create these teams: `Workstations`, `Workstations (canary)`, `Servers`, and `Servers (canary)`.
Fleet's best practice teams:
- `Workstations`: End user's production work computers (macOS, Windows, and Linux)
- `Workstations (canary)`: IT team's test work computers. Sometimes, for demos or testing, includes end user's work computers. Used for [dogfooding](https://en.wikipedia.org/wiki/Eating_your_own_dog_food) a new workflow or feature that may or may not be rolled out to the "Workstations" team.
- `Servers`: Security team's production servers.
- `Servers (canary)`: Security team's test servers.
- `Compliance exclusions`: All contributors' test work computers or virtual machines (VMs). Used for validating workflows for Fleet customers or reproducing bugs in the Fleet product.
- `iPhones`: All contributors' test iOS hosts. Used to dogfood Fleet's iOS features (coming soon).
If some of your hosts don't fall under the above teams, what are these hosts for? The answer determines the the hosts' risk/compliance needs, and thus their security basline, and thus their "team" in Fleet. If the hosts' have a different compliance needs, and thus different security baseline, then it's time to create a new team in Fleet.
## Adding hosts to a team
Hosts can only belong to one team in Fleet.
You can add hosts to a new team in Fleet by either enrolling the host with a team's enroll secret or by transferring the host via the Fleet UI after the host has been enrolled to Fleet.
To automatically add hosts to a team in Fleet, check out the [**Adding hosts** documentation](https://fleetdm.com/docs/using-fleet/adding-hosts#automatically-adding-hosts-to-a-team).
> If a host was previously enrolled using a global enroll secret, changing the host's osquery enroll
> secret will not cause the host to be transferred to the desired team. You must delete the
> `osquery/osquery.db` file on the host, which forces the host to re-enroll
> using the new team enroll secret. Alternatively, you can transfer the host via the Fleet UI, the
> fleetctl CLI using `fleetctl hosts transfer`, or the [transfer host API endpoint](https://fleetdm.com/docs/using-fleet/rest-api#transfer-hosts-to-a-team).
## Advanced
You can automatically enroll hosts to a specific team in Fleet by installing a fleetd with a team enroll secret. Learn more [here](./enroll-hosts.md#enroll-host-to-a-specific-team).
Changing the host's enroll secret after enrollment will not cause the host to be transferred to a different team.
<meta name="pageOrderInSection" value="1000">
<meta name="description" value="Learn how to group hosts in Fleet to apply specific queries, policies, and agent options using teams.">

4
ee/cis/win-10/README.md
View file

@ -1,6 +1,6 @@
# Windows 10 Enterprise benchmarks
Fleet's policies have been written against v2.0.0 of the benchmark. You can refer to the [CIS website](https://www.cisecurity.org/cis-benchmarks) for full details about this version.
Fleet's policies have been written against v3.0.0 of the benchmark. You can refer to the [CIS website](https://www.cisecurity.org/cis-benchmarks) for full details about this version.
For requirements and usage details, see the [CIS Benchmarks](https://fleetdm.com/docs/using-fleet/cis-benchmarks) documentation.
@ -12,4 +12,4 @@ For requirements and usage details, see the [CIS Benchmarks](https://fleetdm.com
### Checks that require a Group Policy template
Several items require Group Policy templates in place in order to audit them.
These items are tagged with the label `CIS_group_policy_template_required` in the YAML file, and details about the required Group Policy templates can be found in each item's `resolution`.
These items are tagged with the label `CIS_group_policy_template_required` in the YAML file, and details about the required Group Policy templates can be found in each item's `resolution`.

Some files were not shown because too many files have changed in this diff Show more