FleetDM

FleetDM is an open-source-friendly osquery fleet manager. The FleetDM connector polls the Fleet REST API for two distinct event streams:

1. Host posture changes — hosts going online, offline, or missing.
2. Saved-query report rows — every row of every saved query, normalized as one event per row.

Severity is derived per-stream so that posture changes and query rows can be routed independently downstream.

What you get

Source	Fleet endpoint	Notes
Hosts	GET /api/v1/fleet/hosts	One event per host whose status changed since since_seconds
Saved queries	GET /api/v1/fleet/queries	Discovery only
Saved-query report rows	GET /api/v1/fleet/queries/{id}/report	One event per row

Events are normalized with category: endpoint. The kind field on the event distinguishes host vs query_row so playbooks and detections can branch.

Prerequisites

• A reachable Fleet server (https://fleet.example.com).
• A long-lived API token issued from Settings → Users → [user] → Get API token.
• Optional Team ID if you want to scope polling to a single Fleet team.

Setup walkthrough

1. Issue an API token in Fleet

1. Sign in to Fleet as a global admin or team admin.
2. Open Settings → Users, select the service-account user, and click Get API token.
3. Copy the token.

Tokens are scoped to the user. Use a dedicated service-account user so revocation does not lock out a real operator.

2. Add the connector in AiSOC

1. Connectors → Add connector → FleetDM.
2. Fill in base_url (no trailing slash; /api is appended automatically), api_token, and optionally team_id.
3. Test connection — the connector calls GET /api/v1/fleet/me to validate auth.
4. Save.

Polling details

• Default interval: 300 seconds, overridable per-instance via connector_config.poll_interval_seconds.
• The connector pulls hosts and saved-query reports independently in the same poll cycle so a slow saved query does not block host posture ingestion.

Severity mapping

Host posture

Fleet status	AiSOC severity
missing	medium
offline	low
online	info

Saved-query report rows

Identical table-driven mapping as the osctrl connector — persistence and execution tables (startup_items, scheduled_tasks, launchd, crontab, kernel_modules, browser_extensions) get high, file_events gets medium, inventory tables get info.

Troubleshooting

auth failure 401/403 — the token is invalid or the user has been deleted. Re-issue from the Fleet UI.

team_id is set but no events — confirm the team has hosts assigned and that the saved queries are scheduled against that team.

Many duplicate host events — Fleet emits status transitions on poll, not on change. The detection layer is responsible for deduplication via the standard dedupe_key.

Related

• osctrl — alternative open-source fleet manager.
• Detection coverage — endpoint rules that fire on osquery data.

Live-query response actions (playbook step)

The osquery_live_query playbook step supports FleetDM as a backend, dispatching live campaigns via Fleet's distributed-query API.

Playbook step schema

- id: triage-logged-users
  name: "Get logged-in users from affected host"
  type: osquery_live_query
  params:
    backend: fleetdm
    base_url: "https://fleet.corp.example.com"
    api_token: "{{ secrets.fleetdm_token }}"   # or use username/password below
    # username: admin
    # password: "{{ secrets.fleetdm_password }}"
    template: logged_in_users
    target_hosts:
      - "{{ alert.host }}"
    timeout_seconds: 60

Authentication

FleetDM supports two credential modes:

Mode	Params
API token	api_token
User / password	username + password (token fetched automatically via /api/v1/fleet/login)

The client will authenticate on first use and reuse the token for the duration of the step.

Supported templates

Same allowlist as the osctrl backend — see the osctrl connector for the full table. Templates are backend-agnostic; only the backend: key selects the fleet manager.

Result shape

{
  "results": {
    "hostname-a": [{"user": "root", "type": "user", "host": "hostname-a"}]
  },
  "partial": false,
  "timed_out_hosts": []
}

When to choose FleetDM vs osctrl

Concern	FleetDM	osctrl
Community / ecosystem	Larger	Smaller
Multi-tenant isolation	Teams (paid tier for strict isolation)	Native environments (OSS)
Infra footprint	MySQL + Redis	PostgreSQL only
AiSOC stack alignment	Needs extra deps	Native fit

Both backends are fully supported — choose based on your existing fleet management deployment.