From 7c26f4db81cd1e841612fed897fd0c9fa47dd3c3 Mon Sep 17 00:00:00 2001 From: Herman Slatman Date: Fri, 17 Apr 2026 14:33:46 +0200 Subject: [PATCH 1/3] Add beginning of Osquery extension and custom Fleet report for Linux --- tutorials/connect-fleet-dm-to-smallstep.mdx | 150 +++++++++++++++++++- 1 file changed, 147 insertions(+), 3 deletions(-) diff --git a/tutorials/connect-fleet-dm-to-smallstep.mdx b/tutorials/connect-fleet-dm-to-smallstep.mdx index 477ca9d7..0e0c449d 100644 --- a/tutorials/connect-fleet-dm-to-smallstep.mdx +++ b/tutorials/connect-fleet-dm-to-smallstep.mdx @@ -354,9 +354,84 @@ If your fleet includes multiple Linux distributions or architectures, create sep +## Step 2. Deploy the osquery extension on Linux + +Smallstep provides an osquery extension that registers additional device identity information, including the TPM Endorsement Key (EK)—directly in Fleet. When Smallstep syncs your device inventory from Fleet, it reads this data to enable a more seamless enrollment experience on Linux. + +1. Download the `step-agent-osquery` package for your Linux distribution and target architecture from [Smallstep's releases](https://releases.smallstep.com). +1. In Fleet, go to **Software** +1. Click **Add software**. Ensure a fleet is selected; software is configured per-fleet +1. Select **Custom package** +1. Click **Choose file**, and select the `step-agent-osquery` package that was downloaded before +1. Enable **Deploy** +1. Click **Add software**. + +A modal should appear, showing the package upload progress. + +By default, a policy will be created that automatically triggers package installation when evaluation of the policy fails. The +condition of this policy does not include a minimum software version, so any version of the `step-agent-osquery` package is +accepted. To force a new package version to be installed, a new version of the package must be uploaded via **Software**, and +the policy should be edited to include a condition like `and version >= '0.65.1-1'`. + +See https://fleetdm.com/guides/deploying-custom-osquery-extensions-in-fleet-a-step-by-step-guide for additional guidance and some troubleshooting options when deploying osquery extensions. + + +## Step 3. Create a Smallstep enrollment report in Fleet + +Once the extension is active on your Linux devices, create a Fleet report to collect the enrollment data. Smallstep reads this report during device sync to include the TPM EK and other enrollment details alongside the standard Fleet device inventory. + +1. In Fleet, go to **Reports** +2. Ensure **All Fleets** is active. If not, the report won't apply to all your hosts. +3. Click **Add report** +4. Enter the following query: + + ```sql + SELECT * FROM smallstep_enrollment; + ``` +5. Click **Save**; a modal should appear +6. In the modal, enter the following details: + - A **Name** for the query, such as "Smallstep Enrollment" + - Optionally, a **Description** + - The **Interval** can be set to **Every hour**. While testing, a shorter interval can be helpful + - Optionally, enable the **Observers can run** checkbox + - Enable **Linux** as **Target** + - Select **All hosts** +7. Click **Save** + +## Step 4. Link enrollment report in Smallstep + +Once the enrollment report is configured in Fleet, the Smallstep platform needs to know about its existence, so that it can gather the data reported through it. + +1. Take not of the numeric ID of the Smallstep enrollment report that was just created +2. In the Smallstep platform, edit your Fleet configuration +3. Set the **Enrollment Query ID** to the numeric ID + + +## Step 5. Linux agent configuration + +Linux does not support MDM configuration profiles, so the SCEP enrollment flow used for macOS and Windows does not apply. Instead, the Smallstep agent on Linux registers directly using TPM attestation. After installing the agent package and the osquery extension, you must configure the agent with your Smallstep team slug and CA fingerprint. + +When adding a Linux agent package in Fleet, add the following **post-install script** to configure and start the agent: + +```bash +#!/bin/bash + +# Configure the Smallstep agent +mkdir -p /etc/step-agent +cat > /etc/step-agent/agent.yaml << EOF +team: "" +fingerprint: "" +EOF + +# Enable and start the agent service +systemctl daemon-reload +systemctl enable --now step-agent +``` + + After deployment, Linux devices will self-register with your Smallstep team via TPM attestation. By default, new devices require admin approval in the [Smallstep console](https://smallstep.com/app/?next=/devices). To automate approval, you can [pre-register devices via API](../platform/smallstep-agent.mdx#pre-registration-via-api). -## Step 2. Confirmation (Linux) +## Step 6. Confirmation (Linux) On a Fleet-enrolled Linux host: @@ -592,6 +667,59 @@ Find the Intermediate CA's SHA-1 fingerprint in [**Certificate Manager → Autho ``` +- Replace `YOUR_ROOT_CA_SHA256_FINGERPRINT` with the Root Fingerprint from the Smallstep Agents authority. +- If you used a different CA name in Fleet, replace `SMALLSTEP_AGENT` in the variable names accordingly. + +### Windows Root CA profile (`smallstep-root-ca.xml`) + +To install the Smallstep Agent Root CA on Windows, create a second file called `smallstep-root-ca.xml` using the `RootCATrustedCertificates` CSP: + +```xml + + + + ./Device/Vendor/MSFT/RootCATrustedCertificates/Root/YOUR_ROOT_CA_SHA256_FINGERPRINT/EncodedCertificate + + + b64 + + + + + + +``` + +## Step 5. Deploy the configuration profiles and Smallstep agent + +### Upload profiles + +1. In Fleet, go to **Controls → OS settings → Custom settings** +2. Click **Add profile** +3. Upload your `smallstep-agent.mobileconfig` file (for macOS/iOS) or your `.xml` files (for Windows) +4. Assign the profile to your desired scope (teams or all devices) + +The profiles will be deployed to devices at their next check-in. Fleet will automatically substitute the variables with the appropriate values for each device. + +### Deploy the agent + +The last step is to deploy the [Smallstep agent](../platform/smallstep-agent.mdx) to your endpoints. The agent manages certificates and makes it easy to configure endpoints. + +You can deploy the agent using Fleet's [software deployment](https://fleetdm.com/guides/deploy-software-packages) feature: +1. Download the agent package: + - macOS: [step-agent-plugin_latest.pkg](https://packages.smallstep.com/stable/darwin/step-agent-plugin_latest.pkg) + - Windows (x64): [step-agent-plugin_latest_amd64.msi](https://packages.smallstep.com/stable/windows/step-agent-plugin_latest_amd64.msi) + - Windows (ARM64): [step-agent-plugin_latest_arm64.msi](https://packages.smallstep.com/stable/windows/step-agent-plugin_latest_arm64.msi) + - Linux (Debian/Ubuntu x64): [step-agent-plugin_amd64_latest.deb](https://packages.smallstep.com/stable/linux/step-agent-plugin_amd64_latest.deb) + - Linux (Debian/Ubuntu ARM64): [step-agent-plugin_arm64_latest.deb](https://packages.smallstep.com/stable/linux/step-agent-plugin_arm64_latest.deb) + - Linux (RHEL/Fedora x64): [step-agent-plugin_x86_64_latest.rpm](https://packages.smallstep.com/stable/linux/step-agent-plugin_x86_64_latest.rpm) + - Linux (RHEL/Fedora ARM64): [step-agent-plugin_aarch64_latest.rpm](https://packages.smallstep.com/stable/linux/step-agent-plugin_aarch64_latest.rpm) +2. In Fleet, go to **Software**, choose **Custom Package**, and add the package for distribution + +Alternatively, you can use a separate software management system such as [Munki](https://github.com/munki/munki) to deploy the agent. See the [Smallstep Agent manual installation guide](../platform/smallstep-agent.mdx#macos-installation) for detailed instructions. + +Replace `` with your Smallstep team slug (found in [**Settings → Team**](https://smallstep.com/app/?next=/settings/team)), and `` with the SHA-256 root fingerprint of your Smallstep Agents authority (found in [**Certificate Manager → Authorities**](https://smallstep.com/app/?next=/cm/authorities) under the Agents authority). +
**Why two profiles?** Fleet enforces a homogeneity rule on Windows configuration profiles: a profile that contains any `ClientCertificateInstall/SCEP/` LocURI cannot also contain `RootCATrustedCertificates/...` LocURIs (or vice-versa). Combining the two CSPs in one profile additionally crashes Fleet's API with a 502 that the UI swallows silently, so the profile never appears. Two profiles is the only path that works. @@ -705,8 +833,8 @@ fleet-gitops/ ``` - `default.yml` — Organization-wide settings, including certificate authorities -- `teams/team.yml` — Per-team configuration for profiles and software -- `lib/` — Configuration profile files and the Linux agent setup script +- `teams/team.yml` — Per-team configuration for profiles, software, and queries +- `lib/` — Configuration profile files and Linux agent setup script ## Add the certificate authorities @@ -801,6 +929,22 @@ Adapt the label names to match your Fleet label configuration. Fleet includes bu The PowerShell registry script from the Windows [Step 6](#step-6-configure-the-smallstep-agent-via-a-powershell-script) is run from the Fleet UI rather than GitOps. If you want it under version control, manage it through Fleet's [scripts API](https://fleetdm.com/docs/rest-api/rest-api#scripts). +## Add the enrollment query + +Add the Smallstep enrollment query to your team YAML. Fleet will collect results from all hosts on a schedule and expose them as a report: + +```yaml +queries: + - name: Smallstep enrollment + description: Collects Smallstep enrollment data including TPM EK for device identity sync + query: SELECT * FROM smallstep_enrollment; + interval: 3600 + platform: linux + automations_enabled: true + logging: snapshot + discard_data: false +``` + ## Apply the configuration Run `fleetctl gitops` to apply the configuration: From 6597fc509f6a44219fdb294297050d591b02500c Mon Sep 17 00:00:00 2001 From: Herman Slatman Date: Thu, 28 May 2026 22:53:25 +0200 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: Carl Tashian --- tutorials/connect-fleet-dm-to-smallstep.mdx | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/tutorials/connect-fleet-dm-to-smallstep.mdx b/tutorials/connect-fleet-dm-to-smallstep.mdx index 0e0c449d..9d99a9b3 100644 --- a/tutorials/connect-fleet-dm-to-smallstep.mdx +++ b/tutorials/connect-fleet-dm-to-smallstep.mdx @@ -368,10 +368,7 @@ Smallstep provides an osquery extension that registers additional device identit A modal should appear, showing the package upload progress. -By default, a policy will be created that automatically triggers package installation when evaluation of the policy fails. The -condition of this policy does not include a minimum software version, so any version of the `step-agent-osquery` package is -accepted. To force a new package version to be installed, a new version of the package must be uploaded via **Software**, and -the policy should be edited to include a condition like `and version >= '0.65.1-1'`. +After upload, a Fleet policy is created that automatically triggers package installation if the package is not yet installed. This policy has no minimum version requirement—any version of `step-agent-osquery` is accepted. To force a new package version to be installed, upload the package to Fleet and edit the policy to include a condition like `and version >= '0.65.1-1'`. See https://fleetdm.com/guides/deploying-custom-osquery-extensions-in-fleet-a-step-by-step-guide for additional guidance and some troubleshooting options when deploying osquery extensions. @@ -402,8 +399,8 @@ Once the extension is active on your Linux devices, create a Fleet report to col Once the enrollment report is configured in Fleet, the Smallstep platform needs to know about its existence, so that it can gather the data reported through it. -1. Take not of the numeric ID of the Smallstep enrollment report that was just created -2. In the Smallstep platform, edit your Fleet configuration +1. Note the numeric ID of the Smallstep enrollment report that was just created +2. In the Smallstep console, edit your Fleet configuration 3. Set the **Enrollment Query ID** to the numeric ID From 1484320593d9eec0b182827f9f61e586fa1f640a Mon Sep 17 00:00:00 2001 From: Herman Slatman Date: Thu, 28 May 2026 22:58:10 +0200 Subject: [PATCH 3/3] Remove remnants from rebase that went awry --- tutorials/connect-fleet-dm-to-smallstep.mdx | 53 --------------------- 1 file changed, 53 deletions(-) diff --git a/tutorials/connect-fleet-dm-to-smallstep.mdx b/tutorials/connect-fleet-dm-to-smallstep.mdx index 9d99a9b3..eaa7d20a 100644 --- a/tutorials/connect-fleet-dm-to-smallstep.mdx +++ b/tutorials/connect-fleet-dm-to-smallstep.mdx @@ -664,59 +664,6 @@ Find the Intermediate CA's SHA-1 fingerprint in [**Certificate Manager → Autho ``` -- Replace `YOUR_ROOT_CA_SHA256_FINGERPRINT` with the Root Fingerprint from the Smallstep Agents authority. -- If you used a different CA name in Fleet, replace `SMALLSTEP_AGENT` in the variable names accordingly. - -### Windows Root CA profile (`smallstep-root-ca.xml`) - -To install the Smallstep Agent Root CA on Windows, create a second file called `smallstep-root-ca.xml` using the `RootCATrustedCertificates` CSP: - -```xml - - - - ./Device/Vendor/MSFT/RootCATrustedCertificates/Root/YOUR_ROOT_CA_SHA256_FINGERPRINT/EncodedCertificate - - - b64 - - - - - - -``` - -## Step 5. Deploy the configuration profiles and Smallstep agent - -### Upload profiles - -1. In Fleet, go to **Controls → OS settings → Custom settings** -2. Click **Add profile** -3. Upload your `smallstep-agent.mobileconfig` file (for macOS/iOS) or your `.xml` files (for Windows) -4. Assign the profile to your desired scope (teams or all devices) - -The profiles will be deployed to devices at their next check-in. Fleet will automatically substitute the variables with the appropriate values for each device. - -### Deploy the agent - -The last step is to deploy the [Smallstep agent](../platform/smallstep-agent.mdx) to your endpoints. The agent manages certificates and makes it easy to configure endpoints. - -You can deploy the agent using Fleet's [software deployment](https://fleetdm.com/guides/deploy-software-packages) feature: -1. Download the agent package: - - macOS: [step-agent-plugin_latest.pkg](https://packages.smallstep.com/stable/darwin/step-agent-plugin_latest.pkg) - - Windows (x64): [step-agent-plugin_latest_amd64.msi](https://packages.smallstep.com/stable/windows/step-agent-plugin_latest_amd64.msi) - - Windows (ARM64): [step-agent-plugin_latest_arm64.msi](https://packages.smallstep.com/stable/windows/step-agent-plugin_latest_arm64.msi) - - Linux (Debian/Ubuntu x64): [step-agent-plugin_amd64_latest.deb](https://packages.smallstep.com/stable/linux/step-agent-plugin_amd64_latest.deb) - - Linux (Debian/Ubuntu ARM64): [step-agent-plugin_arm64_latest.deb](https://packages.smallstep.com/stable/linux/step-agent-plugin_arm64_latest.deb) - - Linux (RHEL/Fedora x64): [step-agent-plugin_x86_64_latest.rpm](https://packages.smallstep.com/stable/linux/step-agent-plugin_x86_64_latest.rpm) - - Linux (RHEL/Fedora ARM64): [step-agent-plugin_aarch64_latest.rpm](https://packages.smallstep.com/stable/linux/step-agent-plugin_aarch64_latest.rpm) -2. In Fleet, go to **Software**, choose **Custom Package**, and add the package for distribution - -Alternatively, you can use a separate software management system such as [Munki](https://github.com/munki/munki) to deploy the agent. See the [Smallstep Agent manual installation guide](../platform/smallstep-agent.mdx#macos-installation) for detailed instructions. - -Replace `` with your Smallstep team slug (found in [**Settings → Team**](https://smallstep.com/app/?next=/settings/team)), and `` with the SHA-256 root fingerprint of your Smallstep Agents authority (found in [**Certificate Manager → Authorities**](https://smallstep.com/app/?next=/cm/authorities) under the Agents authority). -
**Why two profiles?** Fleet enforces a homogeneity rule on Windows configuration profiles: a profile that contains any `ClientCertificateInstall/SCEP/` LocURI cannot also contain `RootCATrustedCertificates/...` LocURIs (or vice-versa). Combining the two CSPs in one profile additionally crashes Fleet's API with a 502 that the UI swallows silently, so the profile never appears. Two profiles is the only path that works.