Osquery Updates

Admin only. This panel is hidden from non-admin operators. If the tab isn’t visible in your Settings nav, your account doesn’t have the Admin role.

osquery is the inspection engine your Mimir agents wrap. Every host runs osqueryd underneath the agent, and bumping the osquery version across the fleet is its own separate decision from bumping the Mimir agent itself. This panel is where you register the new osquery binary, approve it (a deliberate two-step that catches accidental pushes), and roll it out to a chosen percentage of the fleet using the same deterministic-cohort logic that drives Agent Updates.

Where Mimir agent rollout is one knob (“the dial”), osquery rollout is matrixed across (os, arch) because the binary is platform-specific. You can have version 5.12.1 registered for linux/amd64 at 50% rollout, the same version for darwin/arm64 at 0% (paused), and 5.11.4 still approved-and-active for windows/amd64 at 100% — all on the same panel at the same time.

The deeper plumbing — where the binary file lives, how the SHA256 was computed, how the Ed25519 manifest signature was produced — lives in your operator runbook and the CI signing pipeline. Your job on this panel is to paste in the values the pipeline gives you, click Register, click Approve, and pick a rollout percentage.

What you get

A single card titled Registered versions with a Register version button in the top-right corner. The body of the card is one of two views:

Empty state when no osquery versions are registered:

No osquery versions registered. Register a signed version to enable osquery auto-updates across the fleet.
Table once there’s at least one row:
- Version — the version string in monospace (e.g. 5.12.1).
- Platform — a pill showing os/arch (linux/amd64, darwin/arm64, windows/amd64, freebsd/amd64).
- Added — when the row was first registered, in your Time & Display format.
- Status — Approved (green) or Pending (muted).
- Rollout — a row of preset buttons: 0%, 1%, 5%, 25%, 100%. The currently-set value is outlined in the accent color. — if the row is still pending (rollout is unavailable until approved).
- Actions — Approve for pending rows; Delete for any row, but greyed out while rollout is above 0.

A footer note below the card spells out the two non-obvious rules:

Versions must be approved before rollout. Set rollout to 0% to pause a version. Cohort assignment is deterministic — the same host always gets the same answer for a given version and rollout %.

How to register a new version

Open Settings → Osquery Updates.
Click Register version in the top-right corner. The modal opens.
Fill in the form:
- Version — exactly the upstream osquery version string (5.12.1, 5.11.4). Mimir doesn’t enforce a particular format; whatever you type lands in the table as-is. Use the same string osquery’s --version flag would print.
- OS — dropdown: linux, darwin, windows, freebsd. Pick the operating system this binary targets.
- Arch — dropdown: amd64, arm64. Pick the CPU architecture.
- Download URL — must start with /api/. The form’s muted hint reads (must start with /api/). This is the path your agents will fetch the binary from — typically /api/v1/osquery/binary/<os>/<arch>/<version>/osqueryd.
- SHA256 — exactly 64 hex characters. The agent verifies this against the downloaded bytes before installing.
- Manifest signature — hex-encoded Ed25519 signature over the manifest (128 hex characters). Your CI pipeline produces this value; the field hint reads (Ed25519, hex). Paste the value verbatim. The agent verifies the signature at download time by hex-decoding this string; an empty, truncated, or otherwise-encoded value (base64, raw bytes) fails verification and every agent rejects the binary.
- Manifest timestamp — RFC 3339 UTC (e.g. 2026-04-04T12:00:00Z). The agent uses this to check freshness; the GUI does not interpret it beyond passing it to the server.
The modal footer reminds you:

Signature and timestamp are generated by the CI signing step (scripts/sign-osquery-manifest.sh). For direct binary uploads, use mimir-cli or POST multipart/form-data to the API.
Click Register.

A toast confirms osquery X.Y.Z (os/arch) registered. The row appears in the table with Status: Pending and a — in the Rollout column.

How to approve a pending row

A pending row can’t be rolled out. The two-step Register → Approve is deliberate: it catches CI publishing a manifest you didn’t expect (the row appears, but the dial doesn’t budge), and it gives a second admin the chance to eyeball the version and SHA before agents start downloading it.

Find the row in the Pending state.
Click Approve on the right.
The button briefly shows Approving…; on success the Status column flips to Approved and the Rollout column becomes a row of preset buttons.

A toast confirms osquery X.Y.Z (os/arch) approved. The row is now eligible for rollout, but the percentage is still 0 — you have to click a preset and that’s a separate action.

How to roll out an approved version

Once a row is approved, the Rollout column shows five preset buttons:

Preset	Effect
`0%`	Paused. No host of this `os/arch` gets the new osquery yet.
`1%`	A tiny canary — typically 1 host in 100, deterministic.
`5%`	First real soak band. Catches OS-family-specific regressions.
`25%`	Mid-stage. Most regressions visible by now.
`100%`	Full fleet. Every host of this `os/arch` gets the new osquery.

Click a button and the change saves immediately (no separate Save). A toast confirms Rollout set to N%. The previously selected button loses its accent outline; the new one gains it.

The preset set is deliberately bottom-heavy (0/1/5/25/100) rather than the Agent Updates panel’s 0/10/25/50/100. osquery upgrades are heavier — they replace a system binary and restart the inspection engine — so the typical pattern leans on the small-canary stages longer.

What “deterministic cohort assignment” means here

Same logic as Agent Updates, scoped per (os, arch):

Every host gets a cohort number from its host id and the osquery version string. The same host always lands at the same number for a given version.
Bumping the rollout from 5% to 25% means the 5% that already got the new osquery still have it, plus another 20% join.
Pausing (drop to 0%) freezes the cohort — already-upgraded hosts stay on the new osquery, but no new hosts cross over on their next check-in.

The cohort is recomputed every time a new osquery version is registered (because the version string is part of the input). A host that was in the “fast 5%” for 5.11.4 will land at a different cohort number for 5.12.1. Same property as Agent Updates.

How to delete a registered version

Set the Rollout for the row to 0% first. The Delete button is greyed out while rollout is above 0 — the tooltip reads Set rollout to 0% before deleting. This guard prevents you from yanking the binary out from under an active rollout.
Click Delete.
Confirm in the modal:

Delete osquery X.Y.Z (os/arch)? This cannot be undone. Agents currently running this version are unaffected.
Click Delete.

The row disappears. The footer’s promise holds: agents that have already downloaded and switched to this osquery version stay on it — Mimir doesn’t push downgrades, and the row’s disappearance only stops future hosts from picking up the same binary. To actually roll a fleet back from a problematic version, set the problematic version’s rollout to 0% (or delete it after setting to 0%) and approve a previous version’s manifest with rollout above 0%. The server then serves whichever approved, non-paused row was approved most recently for that (os, arch), and each agent’s cohort decides whether it qualifies for that row at the current rollout %.

Working with multiple platforms

A single osquery upstream release usually means registering four to six rows on this panel: one per (os, arch) your fleet actually runs. Common pattern:

Register the linux/amd64 row first (typically the biggest slice of the fleet). Approve, roll to 1%, watch for an hour.
Once stable, register linux/arm64, darwin/amd64, darwin/arm64, windows/amd64. Approve each.
Roll each (os, arch) independently at the cadence your team prefers — some teams roll all platforms in lockstep, some stagger Windows behind Linux because the Windows release is higher-risk historically.

Each row is independent. Pausing darwin/arm64 doesn’t pause linux/amd64; bumping linux/amd64 to 100% doesn’t affect any other platform. The panel scales horizontally as your platform matrix grows.

Troubleshooting

Registration failed. The most common cause is the SHA256 field — the form’s pattern="[a-fA-F0-9]{64}" rejects anything other than exactly 64 hex chars, but the server additionally verifies the SHA matches what the manifest signature covers. Re-paste both the SHA and the signature; a copy-paste mismatch between them is the usual culprit.

Approve failed. Almost always the server-side signature check (Ed25519) rejected the manifest. This means the Manifest signature field was wrong at registration time, or the manifest’s signed contents have drifted. Re-register with values freshly generated by your CI signing pipeline.

Rollout preset clicks but nothing happens. The button is disabled (greyed) when the current rollout already matches the clicked preset. Watch the accent outline — it lives on the currently-saved preset.

Delete is greyed out and I really need to remove the row. Set rollout to 0%, save (the rollout click is the save), and then click Delete. There is no override.

Agents aren’t picking up the new osquery even at 100%. Two common cases. (1) The agents haven’t checked in yet — osquery updates use the same 4-hour-plus-jitter poll plus 24h client-side stagger as agent updates, so plan for up to a day between clicking 100% and every reachable host having the new binary, not four hours. See the Agent Updates page for the lag breakdown. (2) The agent installer didn’t enable osquery auto-updates on those hosts at install time. That’s an agent-side configuration the GUI can’t surface; check with whoever provisioned the agents.