Skip to main content

Fleet Policies, Rollouts, and Device Posture

This guide covers the three pillars of the Fleet MDM value story: centralized governance policies that control what AI agents can do on every enrolled machine, staged rollouts that update ssg across your fleet safely, and device posture that tells you which machines are actually protected.

What Fleet policies do​

A SigmaShake Fleet policy is a named, versioned set of .rules governance directives that the Fleet control plane compiles into a signed bundle and distributes to every enrolled agent.

When an agent receives a new policy bundle:

  • Its local ssg governance engine replaces the previous rules with the new bundle.
  • Every AI tool call from that point forward is evaluated against the new rules.
  • The agent reports policy compliance on its next heartbeat.

This gives you centralized governance — one change in the Fleet dashboard reaches enrolled machines on their next heartbeat, which is every 5 minutes while the machine is online. Offline machines apply it after they reconnect. This is an unmeasured best case, not a guarantee. No action is needed from individual developers.

Authoring a policy​

1. Find a ruleset​

Fleet policies reference rulesets by their slug from the Hub Catalog. Browse hub.sigmashake.com or the Hub Catalog tab in the Fleet dashboard to find rulesets that match your risk profile.

Common starter choices:

Ruleset slugWhat it does
agent-safety-baselineDENY catastrophic actions (mass-delete, disk-wipe, credential-theft, ransomware loop) + ASK for irreversible ops
protect-databaseASK before any destructive schema or data operation
protect-secretsASK for reads of .env, credential files, and key material
safe-writesRestrict writes to sensitive system paths

2. Create the policy​

In the Fleet Dashboard → Policies → New policy:

  1. Enter a name (e.g., "Dev team baseline").
  2. Add one or more ruleset slugs from the Hub Catalog.
  3. Optionally add a description for audit clarity.
  4. Click Save as draft.

3. Submit and approve​

Policies follow a two-step change gate to prevent accidental fleet-wide changes:

  1. A policy_author or org_admin submits the policy for review.
  2. An org_admin approves it. Approved policies move to the active state.

4. Compile and distribute​

Click Compile policies (or call POST /api/v1/orgs/:org/policies/compile) to merge all active policies into a signed bundle. Agents pick up the bundle on their next heartbeat (every 5 minutes while online) or immediately if a real-time poke is sent and the agent is connected. Offline agents pick it up after they reconnect.

Instant propagation

To push a policy change immediately without waiting for the heartbeat cycle, use the real-time poke:

# Via the Fleet API (requires org_admin bearer)
curl -X POST https://{SUBDOMAIN}.fleet.sigmashake.com/api/v1/orgs/{ORG_ID}/agents/poke \
  -H "Authorization: Bearer {SERVICE_ACCOUNT_KEY}"

This sends a reconcile signal to all connected agent WebSockets. Agents not currently connected will pick up the change on their next heartbeat.

Staged rollouts (MDM updates)​

Fleet's rollout system lets you update the ssg version on enrolled machines in controlled stages — the same model used by enterprise endpoint management platforms.

Creating a rollout​

In the Fleet Dashboard → Updates → New rollout:

  1. Target version — the ssg semver to deploy (e.g., 0.29.158). Must be a published version.
  2. Agent selector — choose a targeting strategy:
    • All agents in the org
    • A specific named group
    • A filter expression (e.g., os=linux AND version_lt=0.29.155)
  3. Submit. Each matched agent receives an update directive on its next heartbeat.

Rollout states per agent​

StateMeaning
dispatchedDirective sent; agent has not yet acknowledged
convergedAgent received and started the update
succeededAgent confirmed running the target version
failedAgent reported an error; see the agent detail for the error message
skippedAgent declined (e.g., SSG_FLEET_NO_REMOTE_UPDATE=1, or installed via brew/pip/winget)
sweptTask abandoned by the background sweep (agent went silent)

Rollout safety constraints​

  • The target version must be a strict semver string. Non-semver values (URL-like, git ref) are rejected to prevent package-manager injection (RCE vector). The internal security review of the Fleet MDM agent-update subsystem dated 2026-05-20 (an internal, AI-assisted review by Claude, not a third-party penetration test) found the missing version check as finding F-1 (High) and confirmed the fix. It also fixed F-2 (Medium, audit coverage). Other findings from that review, such as F-3 (no SigmaShake-side check of the update artifact), are still open.
  • Rollout steps are written to the Fleet audit chain (rollout.completed, agent.update.succeeded, etc.). An agent reports its own update success and version; Fleet does not verify them independently (review finding F-5, open).
  • Use cancel rollout to stop a rollout in progress if a bad version is deployed. Use retry failed to re-queue agents that errored.

Device posture​

Fleet's posture layer answers the question: are the machines that should be protected actually protected?

Coverage assurance​

The Coverage report (Agents → Coverage tab) compares:

  • Expected — the machines you declared via a coverage manifest (PUT /api/v1/orgs/:org/coverage/expected)
  • Enrolled — the machines that have an active agent

Machines in expected but not in enrolled are dark assets — machines that should be governed but are not. The coverage rate is enrolled_matching / expected_total.

Uploading a manifest:

{
  "expected": [
    { "ext_id": "laptop-001", "label": "Alice's MacBook", "os": "darwin" },
    { "ext_id": "laptop-002", "label": "Bob's Linux box", "os": "linux" },
    { "ext_id": "ci-runner-1", "label": "GitHub Actions runner", "os": "linux" }
  ]
}
curl -X PUT https://{SUBDOMAIN}.fleet.sigmashake.com/api/v1/orgs/{ORG_ID}/coverage/expected \
  -H "Authorization: Bearer {SERVICE_ACCOUNT_KEY}" \
  -H "Content-Type: application/json" \
  -d @manifest.json

Policy compliance posture​

The Health screen shows policy compliance rate — the percentage of active agents running the latest compiled policy bundle. An agent is non-compliant if it has not yet pulled the latest bundle (e.g., was offline during the compile window).

Lifecycle posture​

Agents age through a lifecycle state machine (active → idle@7d → stale@30d → offline@90d → tombstoned@180d) driven by heartbeat silence. The Health screen surfaces lifecycle breakdowns so you know how many machines are active vs. drifting toward stale.

Governance evidence for compliance​

Every policy approval, compile, and agent-pull is recorded in the fleet audit log, a linear SHA-256 hash chain (not a Merkle tree). The GET /api/v1/orgs/:org_id/compliance/soc2 endpoint is for org_admin users only. It is an asynchronous job: it queues a report job, returns 202 with a poll_url, and you poll GET /api/v1/orgs/:org_id/compliance/:job_id for the status. The result is a self-generated evidence report. It is not an audit or an attestation.

Audit events relevant to compliance:

EventWhen it fires
policy.compiledA new bundle was compiled and stored
policy.approvedA policy was approved by an org_admin
agent.policy.pulledAn agent downloaded the latest bundle
rollout.completedAll targeted agents have reached a terminal state
agent.lifecycle.purgedA stale agent record was hard-deleted after 180 days