Fleet Policy & Agent Signing

What It Does

The policy a device receives is a set of switches — turn on the firewall and, on a Mac, disable remote login or require a screen lock, and so on — worked out from the profiles that device is in scope for. Nothing is enforced by default, and where profiles overlap the strictest setting wins. There are two master switches, one for security settings and one for operating-system updates: while either is off, the agent is told nothing about the controls under it, which it reads as “do not touch this machine”. A master switch comes on for a device only when a profile covering it carries a control from that family, and only then does the agent start changing settings on the endpoint.

If something here is not working as you expect, start with When something goes wrong.

The per-OS hardening policy your instance publishes, and the exact ECDSA-P256 signature every agent heartbeat carries — specified so an inspector can reconstruct and verify it byte-for-byte.

Per-OS Policy API

The per-platform agent settings are stored as one row per platform — macos, linux, windows. GET /devices/policy returns all three at once (keyed { macos, linux, windows }) so the UI can render one panel per OS. PUT /devices/policy targets a single platform via a platform field in the body (default macos for older callers); any unrecognised value folds to macos. Both endpoints reach device-service through the authenticated gateway path /user-management/devices/policy. Hardening and update controls are not written here any more: once an instance’s old settings have been moved into its Baseline profiles, GET returns profilesOnly: true and a PUT that would change one of those flags is refused with 409 (“managed in Profiles now”). The profile routes are in MDM & Device Operations.

The Compliance Key Set

These are the fields the heartbeat response carries; each is switched on by a profile payload rather than set directly. Every hardening control is a boolean gated behind manageCompliance. Some keys are shared across platforms; the agent for each OS deserialises only the fields it declares, so a key it does not use is simply ignored. The full set the source stores and serves:

The Two Gates And What OFF Serves

This is the invariant to verify. The stored row always holds a concrete boolean for each control, but the heartbeat response masks them: when the master switch is off, the control ships as null. The agent treats null as “unmanaged” and does not touch that setting.

Worked Example — Set The macOS Check-In Interval And Minimum OS

Agent Enrollment

An agent has no human session, so it cannot ride the authenticated devices path. It reaches device-service through the one unauthenticated gateway route, /agent, which whitelists exact (method, path) pairs and strips the /agent prefix before proxying. Trust is established downstream: /enroll requires a valid enrollment token; /heartbeat requires a signature.

POST /agent/enroll requires all three of enrollmentToken, serialNumber and publicKey — any missing field is a 400. The public key is imported and its curve checked: a non-P-256 key is a 400 “Public key must be P-256”, an unparseable one a 400 “Invalid public key”. A device row is keyed by the unique serialNumber (on Linux the agent sends a machine ID in that field), so one physical machine is always exactly one row; success returns 201 { deviceId }.

The other refusals. 400 also when serialNumber is longer than 255 characters or contains a NUL character; the serial is refused rather than shortened, so two different long serials can never land on one record. 401 for a bad token, with one of three messages: Invalid enrollment token, Invalid or expired enrollment token (also when the token is revoked or used up), or Enrollment is not configured on this tenant. 403 when the serial belongs to a retired device or a rejected enrollment: an admin must return it to service first. 409 for a changed signing key, described below. The 401, 403 and 409 refusals are audited as DEVICE_ENROLL_REJECTED. Two things happen on success that the status code does not show: a serial seen for the first time is created pending approval and is not trusted until an admin approves it, and a re-enrollment of a known serial cancels every command still queued for that device.

Extra Enrollment Tokens

In plain terms: the Linux and Windows install commands in Devices → Settings already hand out your instance’s reusable enrollment token (valid 90 days and replaced automatically in the last 14), so most administrators never issue a token by hand. These routes exist for the less common case where you want a separate, short-lived token with a fixed number of uses that you can revoke on its own.

label is optional and cut to 120 characters. ttlHours defaults to 24 and is clamped to 1–720 (30 days). maxUses defaults to 1 and is clamped to 1–500. Out-of-range values are clamped, not rejected. The token value is returned once, in the 201 response; only its SHA-256 is stored, so it cannot be shown again. At enrollment a use is reserved atomically, so two machines enrolling at the same moment cannot both spend the last use, and a token that is revoked, expired or used up is answered with 401. The list also shows the instance’s own reusable token, which has no use limit.

Heartbeat Signature Spec

There is no bearer token on the heartbeat. Each request is signed with the device’s private key (held in the Secure Enclave on Apple silicon and T2 Macs when the build is signed for it; a software P-256 key in a root-only file on other Macs and on Linux, and in an administrator-only file under ProgramData on Windows — no OS keychain or TPM is used) over a canonical description of that exact request, and the server re-derives the same string and verifies it against the public key pinned at enrollment. The verifier is shared/utils/deviceAuth.js. The canonical string is six lines joined by \n, in this fixed order — the literal zx-agent-v1 tag is part of the contract:

The signature and its context travel in four namespaced headers on POST /agent/heartbeat. All four are required; the middleware requireDeviceSignature rejects a request missing any of them with 401 “Missing device signature headers”:

• x-zx-device-id — the integer deviceId returned at enrollment (must be a positive integer).
• x-zx-timestamp — the same unix-seconds value on line 4 of the canonical string.
• x-zx-nonce — the one-time nonce on line 5 (rejected as malformed if longer than 200 chars).
• x-zx-signature — base64 DER ECDSA/SHA-256 signature over the canonical string.

Heartbeat Body And Response In Full

In plain terms: besides its inventory, each check-in tells your instance what the agent is able to do, reports how the commands it was given turned out, and says which policy it has applied. The reply hands back the policy for that device, any commands waiting for it, and a newer agent build if there is one. An administrator sees the results as command history on the device and as installed, failed or pending against each profile.

• capabilities — what the agent build understands. Values are trimmed and lower-cased, and unknown ones are ignored. An agent that does not send commands_v2 gets the older response shape with no commands list.
• commandResults — one entry per finished command: id, status (succeeded, failed or unsupported) and a detail string kept to 500 characters. At most 50 are read per check-in. Reporting the same result twice is harmless: a command already settled is skipped.
• commandResultsAccepted — present only for an agent that declared commands_v2, and only when the request carried results. true means they were stored; false means they could not be, and the agent sends them again at the next check-in.
• commands — up to 20 queued commands per check-in, each { id, type, args }. command is the older single slot, which can only carry lock or uninstall; it is set to null when that same command is already in commands, so nothing is delivered twice.
• policyHash — lower-case hex SHA-256 of the canonical JSON of the policy object in this response: object keys sorted at every level, no whitespace, arrays kept in order. It is sent to every agent.
• enforcement — the agent echoes the hash of the policy it applied, with the fields it applied and the ones that failed (up to 200 of each; field names kept to 64 characters, errors to 200). For each profile covering the device, a matching hash with no failed field of that profile is installed; a matching hash with a failed field is failed, with the agent’s error; a different hash is pending, the normal one-check-in lag after a policy change, never a failure. An agent too old to send the report has its profiles marked from the state the device itself reports instead.
• inventory.installedSoftware — structured software list, capped at 2,000 entries. The older inventory.installedApps list of strings is still accepted and is used when the structured list is absent.
• update — null unless the version chosen for this device is strictly newer than the agentVersion it reported, so the server never offers a downgrade. The agent still checks the hash and the release signature before installing, and applies the newer-only rule itself.
• trustBundle — the current vendor trust bundle, which is how a release-signing key is revoked, or null when none is stored. It is sent on every check-in. Both fields are specified under Release Signature And Trust Bundle, further down this page.

A failure while storing results, software or the enforcement report is logged and never fails the heartbeat itself: the agent still gets its 200 and its policy.

Worked Example: Sign And Send One Heartbeat

A shell version of what the agent does, for an inspector who wants to reproduce one check-in. It needs openssl and curl, a P-256 private key in PEM (here device.key) and the deviceId given at enrollment (here 42). The key must be one you generated and enrolled yourself: POST /agent/enroll takes the public half. The macOS agent keeps its key in the Secure Enclave where the Mac has one, and that key cannot be exported to a file. The host is written as on the API reference page. An agent has no session cookie, so no Origin header is involved.

This call is a real check-in, not a read. It sets the device’s last-seen time and address and overwrites the platform and agent version stored for it. A lock or uninstall waiting for that device is handed to this call and marked delivered, so the real agent never receives it; the same happens to every other queued command if the body declares commands_v2, which is why the body below leaves capabilities out. A device shown as uninstalling or uninstalled, with nothing waiting for it, goes back to active. Use a device you enrolled for the test, not one in service.

The Checks, In Order

requireDeviceSignature runs cheapest-first so a forged request never touches the database. Each stage that fails returns 401 with a distinct message an inspector can key on:

• Headers present. Missing device id / timestamp / nonce / signature → Missing device signature headers.
• Freshness. The timestamp must be within ±300 s (TIMESTAMP_WINDOW_SEC) of server time, checked before any DB hit → Stale or invalid timestamp. A nonce over 200 chars → Malformed nonce.
• Known device. The deviceId must resolve to an enrolled row with a pinned publicKey → Unknown or un-enrolled device.
• Signature. ECDSA/SHA-256 verify over the re-derived canonical string → Signature verification failed. A malformed key or signature is a failed verification, never a 500.
• Not retired. Checked by the heartbeat handler after the signature, so only the real device learns why: a retired device (or a rejected enrollment) → Device is retired, until an admin returns it to service.
• Replay. The (deviceId, nonce) pair must be unseen — a unique index is the source of truth, so even two concurrent replays cannot both slip through → Replay detected.

Release Signature And Trust Bundle

In plain terms: an agent installs a newer build of itself only when four things hold, and it checks them itself rather than taking your instance’s word. The build must be newer than the one running, it must arrive over HTTPS, its contents must match the published hash, and the hash must carry a signature made with a Zonitix release key the agent already trusts. The checks are the same on macOS, Linux and Windows. All four are checked before anything is installed. The first three catch an old, insecurely delivered or altered build; the fourth is what stops a build that someone other than Zonitix produced.

What The Agent Checks Before Installing

1. Newer only. update.version must be strictly greater than the version the agent is running. The comparison is numeric on major, minor and patch (a leading v is ignored and a missing part counts as 0), so an equal or older version is refused even when its signature is valid. Your instance applies the same rule before it offers a build, as described under update above; the agent does not rely on that.
2. HTTPS only. A download address that does not start with https:// is refused.
3. Hash. The SHA-256 of the downloaded bytes must equal update.sha256, compared without regard to letter case.
4. Release signature. update.sig must verify against a release key in the agent’s own trust file that is not on its revoked list. A reply with no signature, or an agent with no trust file, is a refusal. The macOS agent uses exactly the key named by update.kid and refuses when that field is missing; the Linux and Windows agents try the key named by kid first and then their other trusted keys.

A refusal leaves the running agent in place, and the device keeps checking in. The reason is written to the agent’s own log, with one exception: the macOS agent skips a version that is not newer without writing a log line.

The Signature Scheme

• Algorithm. ECDSA on the P-256 curve with SHA-256, the same algorithm as the heartbeat signature but a different key: the device key signs heartbeats, a Zonitix release key signs builds.
• What is signed. Three lines joined by a single \n, with no newline after the last: the literal zx-release-v1, the version exactly as sent in update.version, and the lower-case hex SHA-256 of the package. The version is inside the signed text, so a signature made for one build cannot be reused for another version or other bytes.
• Encoding. update.sig is the DER-encoded signature in base64url without padding. The heartbeat signature, by contrast, is standard base64.
• Public keys. Each trusted key is an SPKI public key in PEM, stored with a key ID (kid).

Where The Trusted Keys Live

Each agent reads its trust from one file, release-keys.json, in its own data folder: /etc/zonitix on Linux, ProgramData\Zonitix on Windows and /Library/Application Support/Zonitix on macOS. On Linux and Windows the install command from Devices → Settings writes the file before the agent first starts. It holds public keys only:

• releaseKeys — the release keys the agent accepts, each with kid and publicKeyPem. An entry in the file may also carry alg, which the agent does not read.
• revokedKids — key IDs the agent no longer accepts, even when the key is still listed.
• rootKey — one root public key, { kid, publicKeyPem }. It signs nothing but trust bundles.
• trustVersion — a whole number that only goes up. A file without one counts as 0.

Your instance holds the same public keys and checks the same signature before it hosts a build: adopting a release downloads it, recomputes the hash and verifies the release signature, and refuses to host a build that fails either. See Update The Agent.

How The Trusted Keys Are Replaced

A release key is added or withdrawn on agents already installed by a trust bundle, the trustBundle object in the heartbeat reply: { trustVersion, rootKid, sig, body }. body is the complete new text of release-keys.json. Your instance does not write bundles. It stores the one it receives in the reply to its own license check-in and hands that same object to every agent on every heartbeat. An agent that already holds it refuses it as not newer and keeps its file; that refusal appears in the agent’s log on each check-in and is expected. An agent applies a bundle only when all of these hold:

• The agent has a root key in its trust file, and the bundle’s rootKid equals that key’s ID.
• The root signature verifies. Same algorithm and encoding as a release signature, over three lines joined by \n: the literal zx-trust-v1, trustVersion as a decimal number, and the lower-case hex SHA-256 of the exact bytes of body. A bundle signed with a release key does not verify, so a release key cannot be used to change which keys are trusted.
• It is newer. trustVersion must be strictly greater than the one the agent holds, so an older bundle cannot be replayed to bring back a withdrawn key.
• It keeps the same root. The rootKey inside body must carry the same key ID as the root the agent already holds. A bundle cannot replace the root key.

When every check passes, the agent writes body to a temporary file and renames it over release-keys.json, so the file is never half-written. When any check fails the existing file is left untouched and the reason is logged. A bundle is applied before the commands and before any update carried in the same reply, so a key withdrawn in a check-in cannot authorise an update delivered in that same check-in.