AuditBadger Help Center

FleetDM Integration User Guide

Open in
View as Markdown Open in ChatGPT Open in Claude
M

Maciej Litwiniuk

Last updated on Jul 9, 2026

Overview

AuditBadger connects to FleetDM once at the account level, then uses Fleet host inventory to maintain assets, device assignments, and endpoint compliance evidence.

The integration is designed to avoid duplicate inventory work:

  • Fleet devices are selected by default during the first import review.

  • An exact serial-number match links the Fleet host to the existing AuditBadger asset instead of creating another asset.

  • A Fleet owner email that exactly matches an active AuditBadger user can manage the Fleet-owned checkout automatically.

  • Devices that cannot be matched are shown before import and reported in evidence after import.

  • Devices left outside the import selection are treated as a coverage gap by default.

AuditBadger reads Fleet data but never locks, wipes, enrolls, unenrolls, or otherwise changes a device in Fleet. It also does not retrieve disk recovery keys.

Before You Start

You need:

  • AuditBadger account-admin access.

  • The HTTPS base URL of your Fleet server.

  • A Fleet API-only user token with a read-only role that can read hosts, host counts, device mappings, Fleet configuration, labels, and policies.

  • AuditBadger users with work email addresses matching the owner mappings used in Fleet.

Use a dedicated API-only Fleet user for unattended collection. Keep its access read-only and revoke the user in Fleet if the integration should no longer connect.

Connect FleetDM

  1. In AuditBadger, open Settings > Integrations.

  2. Open FleetDM.

  3. Enter the Fleet server URL, including https://.

  4. Enter the API-only user token.

  5. Click Connect FleetDM.

AuditBadger validates the token and confirms that hosts are readable. The integration page shows the Fleet organization, server, license tier when available, API user, and host count.

If AuditBadger reports that the token belongs to a regular Fleet user, replace it with a dedicated API-only user token so scheduled collection is not tied to an interactive employee account.

Review And Import Devices

After the connection is valid, open Review Devices on the FleetDM integration page. Device import has its own screen so the complete Fleet inventory and every automatic decision can be reviewed together.

The summary shows:

  • Fleet devices: every host visible to the integration token.

  • Existing assets linked: hosts that will update an existing AuditBadger asset.

  • New assets: hosts that will create an asset.

  • Needs attention: hosts with an ownership gap or an asset-matching conflict.

Asset Matching

AuditBadger matches each Fleet host in this order:

  1. The Fleet host ID stored on a previously synced asset.

  2. An exact hardware serial-number match.

  3. The Fleet host UUID stored on a previously synced asset.

For example, if Fleet reports serial P409W6WGWR and one asset in the same AuditBadger account already has serial P409W6WGWR, the importer shows that it will link to that asset. It does not propose a second asset.

AuditBadger does not auto-link when the serial is ambiguous or the asset is already associated with a different Fleet host. The importer disables that host and asks the admin to resolve the asset data first.

Matching is always limited to the current AuditBadger account. A serial in another customer account can never be linked.

Owner Matching

AuditBadger ranks Fleet device-mapping emails by source, then uses the highest-ranked candidate that exactly matches an active AuditBadger user. Email comparison is case-insensitive.

The importer explains one of these outcomes for every host:

  • The owner matched an active AuditBadger user.

  • Fleet supplied an email, but no active AuditBadger user has that email.

  • Fleet supplied multiple possible owners.

  • Fleet did not supply a usable owner email.

No fuzzy name matching is performed. Exact email matching avoids assigning a company device to the wrong person.

Choose The Import Scope

All non-conflicting devices are selected the first time the importer is opened. Usually the admin only needs to review the proposed links, optionally map Fleet platforms to asset categories, and click Save And Sync.

You can deselect a device, but this creates an intentional Fleet coverage gap. The device inventory verifier fails by default while any Fleet device remains outside the AuditBadger import selection.

Map Asset Categories

For each Fleet platform, choose an existing AuditBadger asset category or enter a new category name. Category mapping applies only when an imported asset does not already have a category. Existing manual categories are preserved.

What Sync Changes In AuditBadger

For selected devices, a sync can:

  • Create missing assets.

  • Add Fleet metadata to safely matched existing assets.

  • Fill blank make, model, serial, or category values without overwriting existing manual values.

  • Create, refresh, return, or reassign Fleet-managed checkouts when the device owner matches an active AuditBadger user.

  • Mark previously synced Fleet assets as missing when their host disappears from the selected Fleet data.

Manual checkouts remain authoritative. If a manual checkout conflicts with Fleet ownership, AuditBadger records a conflict and does not overwrite the manual assignment.

Understand Warnings And Failed Checks

The FleetDM integration and its device inventory evidence distinguish several conditions:

Not Imported

Fleet currently exposes more devices than the AuditBadger import selection contains. The complete-coverage verification rule fails by default until the devices are selected or the rule is explicitly relaxed.

No Active AuditBadger Owner

A Fleet device could not be matched to an active AuditBadger user. Selected devices reduce the owner-mapping percentage and can fail the configured threshold. Unselected devices with the same problem also produce an explicit verifier warning so they do not disappear outside the evidence scope.

Ambiguous Owner

Fleet returned multiple equally strong owner mappings. AuditBadger does not guess. Review the device mapping in Fleet, then sync again.

Sync Conflict

The same serial is associated with conflicting Fleet metadata, or a manual checkout disagrees with Fleet ownership. AuditBadger preserves the existing record and reports the conflict for review.

Stale Device

The device has not checked in within the configured number of days. The default device-inventory verification threshold is 30 days.

Evidence Sources

FleetDM can provide four automated evidence sources:

  • Endpoint Device Inventory: import coverage, active AuditBadger owner matching, Fleet status, staleness, and sync conflicts.

  • MDM Enrollment Status: Fleet MDM configuration and per-device enrollment posture.

  • Endpoint Disk Encryption: FileVault, BitLocker, or LUKS posture without recovery keys.

  • Screen Lock Policy Compliance: pass/fail results for the Fleet policies selected as screen-lock evidence.

Use Install Evidence on the integration page to attach the appropriate sources to compliance controls. Screen-lock evidence remains unavailable until at least one Fleet policy is selected.

Troubleshooting

An Existing Asset Is Shown As New

Compare the Fleet hardware serial with the AuditBadger asset serial. They must be an exact match. Also confirm the asset belongs to the same AuditBadger account and is not already linked to a different Fleet host.

A Device Has An Email But No Owner Match

Confirm an active AuditBadger user has exactly that email address. Deactivated, not-yet-active, terminated, or partner-managed users are not valid automatic owners.

A Device Is Missing From AuditBadger

Open Review Devices and confirm the host is selected. If it is visible but unselected, select it and click Save And Sync. If it is not visible, verify that the Fleet API-only user can read that host.

The Importer Cannot Load Hosts

Validate the integration connection. Confirm the Fleet URL is reachable, the token is valid, and the API-only user has read access to hosts and device mappings.

A Manual Checkout Was Not Replaced

This is intentional. AuditBadger never overwrites a manual checkout with Fleet ownership. Resolve the manual checkout or the Fleet mapping, then sync again.

Disconnect FleetDM

Disconnecting stops Fleet sync and evidence collection. Existing assets, checkouts, and collected evidence are retained. Revoke or delete the API-only user in Fleet if its token should no longer be usable.

For product and implementation decisions, see prd_fleetdm-integration.md.